I want to differentiate comments.
In elisp mode, I want to have string in ;;! string highlighted.
(font-lock-add-keywords 'emacs-lisp-mode
'((";;!\\(.*\\)\\\n" 0 'my-important-comment-face)))
However, it is not effective.
This question:
How to test `font-lock-keywords` values for Emacs Lisp code
will point you at some tools that might help you to trace why your code is not being effective.
Related
Today, as I was once again traipsing through the Emacs Manual, I got a little tired and decided to pop into the Org Mode manual for something a little lighter, and I was reading about link handling, and ended up reading (and rereading) the Help documentation for 'org-file-apps.
Well, when I peeked at the related variable 'org-file-apps-windowsnt, I was surprised to see some syntax in its value that I didn't recognise.
To be clear, I've read the elisp manual virtually cover-to-cover, so while it's not uncommon for me to not feel comfortable with a particular bit of syntax, it's fairly rare these days that I don't recognise it at all.
The syntax in question is in the following expression
((remote . emacs)
(system . #f(compiled-function
(file path)
#<bytecode -0x47e8150df949387>))
(t . #f(compiled-function
(file path)
#<bytecode -0x47e8150df949387>)))
Specifically, the #f() syntax.
I tried searching across my Info manuals in Emacs, but only came up with entries related to colour values (e.g., #FFFFFF for white), next I tried DDG and Google, but since all generalised search engines have decided that even something quoted is subject to fuzziness, I haven't turned up anything there.
So, yeah, I'm just hoping somebody can explain the #f() syntax in this bit of Emacs-Lisp code, and what it's doing, and maybe why it's used. I assume it must have something to do with the use of compiled bytecode, but beyond that I'm stumped.
Apologies for what is no doubt a basic question that I've simply forgotten from reading the elisp manual, but searching, including that manual, is getting me nowhere.
I submitted Emacs bug #55853 for this, asking that the f#(...) syntax be documented.
The bug was closed as "fixed" with this explanation. Apparently this is not Lisp-readable syntax but is instead intended to be for human consumption as "pretty-printed" output. I leave it to you whether you think it serves that purpose well. This is the bug-closure explanation:
It's from:
(cl-defmethod cl-print-object ((object compiled-function) stream)
(unless stream (setq stream standard-output))
;; We use "#f(...)" rather than "#<...>" so that pp.el gives better results.
(princ "#f(compiled-function " stream)
I.e., it's from the "pretty" version of prin1, and is not meant to be
readable by the Lisp reader.
[Emacs maintainer Lars has] now mentioned this in the Special Read Syntax node in the lispref [he means the Elisp]
manual in Emacs 28.2.
In other words, this is apparently "special read syntax", i.e., Lisp reader syntax that's not readable by the Lisp reader but is meant to communicate something to humans.
That description "explains the syntax" - the idea behind it. But it doesn't really tell you what the syntax is supposed to communicate to users, i.e., how to read it as a human.
I'd guess it's trying to be a placeholder, in this case, for a (compiled) function that takes arguments FILE and PATH.
What the source code for the function is; what the function does (e.g., it's doc); or where it's defined -- nothing like that is conveyed in the "pretty"-print. And whether "compiled" there means byte-compiled or "native"-compiled also isn't made clear.
Hopefully someone else may be able to add more light with another answer here. And perhaps the 18.2 doc will make things more clear.
I am working on a code parser that is built on Rexx. It is a single file script with around 5000 lines of code or more. I've never worked on Rexx before. Adding to that, the readability issue is making my life even tougher. So,
Are there are any tools to debug and understand Rexx code?
Use the trace statement? The most simple mode of tracing is 'A'. This causes each instruction to be displayed before it is executed. Your instruction is displayed with a line number and the three characters - preceding it, so that you can identify it as a line in your script.
Wikipedia has a pretty good article on Rexx, which should help you understand Rexx syntax and program structure. And almost any Rexx book will apply to your environment, because Rexx is extremely cross-system (similar in that way to the younger Perl and Python languages). There aren't a lot of online books, because almost everything written about Rexx was written before the web existed, but the reference manual for the Regina implementation is, and it's a particularly good reference work.
The date on this question is old, but I'll share what I have found helpful for the next person who pulls this up.
Already mentioned is the TRACE option. I've found this can be overwhelming in a small set of code let alone 5,000 lines or more.Here are some options I've found useful:
Use an "if" to turn the trace on only in certain situations.if counter < 25 then trace "A" Be sure to turn the trace off with:else trace "OFF"
Use say followed by pull. What is said will stay on the screen until you hit enter.
Add a subroutine:
AskIt:
parse pull comment
say comment
say 'enter "X" to exit program'
pull continueif Continue \= "X" then returnexit
This is invoked with call AskIt "In routine that loops, counter=" counter and would display: In routine that loops counter='##enter "X" to exit programThe tester chooses to return to the code by hitting enter or exit the program with X to edit the source.Temporarily inserting return on the line following the routine label will allow you to run the code uninterrupted without removing all the calls.
I have written an edit macro for z/OS which inserts a say *routine name* after every routine label. It inserts the code with a /* comment */ containing a readily identified phrase to simplify cleanup.The audience for this would be small, so I'll not include the code here.
Hope this helps someone.
I was just running style cop against some of my code and got a few:
SA1600: The field must have a documentation header.
Now don't get me wrong I like style cop, it's great when you work on a project with more then one person but this rule seems a bit excessive to me. Why would you want to add:
/// <summary>
/// blah blah blah
/// </summary>
to the top of every variable. I'm pretty sure that I remember someone saying(Martin Fowler, Kent Beck..can't really remember ATM) that comment should say "why" not "what" and I really can't see how you can explain why on a variable.
I also find code that has comments on every variable harder to read because all you see is fluff.
My thoughts are if you have to explain what every variable is then you are really failing in terms of naming.
Does anyone else find commenting variables a bit of a code smell or is it just me.
This is quite an old post but came across it while searching for a solution to this issue myself, so though I would offer a solution.
If you open your Settings.StyleCop file in the rules editor, select the Documentation Rules node, then in the Detailed settings section on the right de-select the Include fields option. Now you will no longer be required to document fields.
I wouldn't say that commenting a variable is always a code smell (and it doesn't sound like that's what you're saying, either). I do agree that commenting every single variable, every single time is at the very least excessive, and possibly indicative of poor naming. In fact, some would argue that any comment is a code smell, and that descriptive names and short routines are more readable and prevent the situation where code has been changed, but the comments haven't been updated (which has certainly bitten me in a few legacy code bases). I don't think I'd take it quite that far, but if you can write code that is self-explanatory without extra explanation, that does seem preferable.
So yeah, basically what you said.
XML Comments are slightly different than other comments.
If you set things up correctly, you can have them appear in tool tips in Visual Studio AND use them to create MSDN style documentation with Sand Castle. I think they should tell you what the thingy is doing when you don't have access to the source code.
The point is that these comments can appear without the source code that they are commenting. They should be helpful to another devloper who can't see your code and could care less how you are doing things.
I don't know about the "Cop" tool you are using, but it would be nice to have a way of signaling the tool that intend to leave a param blank. So:
/// <param name="fubar"></param> // Haven't gotten around to it
/// <param name="portNumber" /> // I intend this parameter to have no help
I have worked on projects where we have to fill everything in and we get things like:
/// <param name="portNumber">The Port Number</param> // What else could it be?
If you don't want to use the features above, go ahead turn off the Style Cop rule.
Totally agree and the first thing I turned off in StyleCop. If you need to explain it, you have named it in a fashion which needs explanation and have failed in making the code self documenting.
For those that still come across this issue, this post how-to-change-a-stylecop-rule actually has the perfect answer.
You should try GhosDoc is an easy way to have documentation automated for every code member on your application. Just install it, right click on the member and select document this!
I think the correct answer here is "it depends." You can certainly explain the "why" of a variable being marked static/const, or business logic/restrictions on the variable's contents. Having said that, I agree that seeing every variable comment impedes readability and can indicate blindly following a standard or improper naming.
Of the following two options for method parameter names that have a unit as well as a value, which do you prefer and why? (I've used Java syntax, but my question would apply to most languages.)
public void move(int length)
or
public void move(int lengthInMetres)
Option (1) would seem to be sufficient, but I find that when I'm coding/typing, my IDE can indicate to me I need a length value, but I typically have to break stride and look up the method's doco to determine the units, so that I pass in the correct value (and not kilometres instead of metres for example). This can be an annoying interruption to a thought process. Option (2) alleviates this problem, but can be verbose, particularly if your unit is metresPerSecondSquared or some such. Which do you think is the best?
I would recommend making your parameter (and method) names as clear as possible, even if they become wordy. You'll be glad when you look at or use the code in 6 months time, or when someone else has to look at your code.
If you think the names are becoming too long, consider rewording them. In your example you could use parameter name int Metres that would probably be clear enough. Consider changing the method name, eg public void moveMetres(int length).
In Visual Studio, the XML comments generated when you enter 3 comment symbols above a method definition will appear in Intellisense hints when you use the method in other locations. Other IDEs may have similar functionality.
Abbreviations should be used sparingly. If absolutely necessary only use commonly known and/or relevant industry-standard abbreviations and be consistent, ie use the same abbreviation everywhere.
Take a step back. Write the code then move on to something else. Come back the next day and check to see if the names are still clear.
Peer reviews can help too. Ask someone who knows the programming language (or just thinks logically), but not the specific functionality, if your naming scheme is clear enough or to help brainstorm alternatives. They might be the poor sap who has to maintain your code in the future!
I would prefer the second approach (i.e. lengthInMeters) as it describes the input needed for the method accurately. The fact that you find it confusing to figure out the units when you are just writing the code would imply it would be much more confusing when you (or some one) looks at the same piece of code later. As regard to issue of the variable name being longer you can find ways to abbreviate it (say "mtrsPerSecondSquared").
Also in defence second approach, the book Code Complete mentions a research that indicates, effort required to debug a program was minimized when variables had names averaged to 10 to 16 characters.
I edited the question after David Hanak's answer (thanks btw!). He helped with the syntax, but it appears that I wasn't using the right function to begin with.
Basically what I want is to let the compiler ignore multiple definitions of a certain label and just use the first. In order to do that, I thought I'd just do something like this:
\makeatletter
\newcommand{\mylabel}[1]{
\#ifundefined{#1}{\label{#1}}{X}
}
\makeatother
This does not work though, because the first option is always chosen (it doesn't matter if the label is defined or not). I think the \#ifundefined (and the suggested \ifundefined) only work for commands and not for labels, but I don't really know much about LaTeX. Any help with this would be great! Thanks!
Much later update:
I marked David Hanak's response as the correct answer to my question, but it isn't a complete solution, although it really helped me.
The problem is, I think but I'm no specialist, that even though David's code checks to see if a label is defined, it only works when the label was defined in a previous run (i.e. is in the .aux file). If two \mylabels with the same name are defined in the same run, the second will still be defined. Also, even if you manage to work around this, it will make LaTeX use the first label that you defined chronologically, and not necessarily the first in the text.
Anyway, below is my quick and dirty solution. It uses the fact that counters do seem to be defined right away.
\newcommand{\mylabel}[1]{%
\#ifundefined{c##1}{%
\newcounter{#1}%
\setcounter{#1}{0}%
}{}%
\ifthenelse{\value{#1} > 0}{}{%
\label{#1}%
\addtocounter{#1}{1}%
}%
}
I'm not sure if it is necessary to initialize the counter to 0, as it seems like a likely default, but I couldn't find if that was the case, so I'm just being safe.
Also, this uses the 'ifthen' package, which I'm not sure is necessary.
I am also not a LaTeX expert, however after one day of trying and searching the internet the following worked for me. I have used a dummy counter to solve the problem. Hopefully this helps, apparently not many people are looking for this.
\newcommand{\mylabel}[1]{
\ifcsname c##1\endcsname%
\else%
\newcounter{#1}\label{#1}%
\fi%
}
# is a special character in LaTeX. To make your declaration syntactically correct, you'll have to add two more lines:
\makeatletter
\newcommand{\mylabel}[1]{
\#ifundefined{#1}{\label{#1}}{X}
}
\makeatother
The first line turns # into a normal letter, the last line reverses its effect.
Update: You might also want to take a look at the "plain" \ifundefined LaTeX macro.
Update 2
Okay, I did some research to figure out the answer to the real problem. The thing is that defining a label does not create a macro by that name; it prepends a "r#" to it. So try the following:
\makeatletter
\newcommand{\mylabel}[1]{
\#ifundefined{r##1}{\label{#1}}{X}
}
\makeatother
For more technical details, refer to line 3863 of latex.ltx in your LaTeX distribution (where it says \def\newlabel{\#newl#bel r}).
By Victor Eijkhout, "TeX by Topic", p.143:
\def\ifUnDefinedCs#1{\expandafter\ifx\csname#1\endcsname\relax}
This can be used to check whether a label is defined; if not, the label is printed:
\newcommand{\myautoref}[1]{\ifUnDefinedCs{r##1}{\color{magenta}\IDontKnow\{#1\}}\else\autoref{#1}\fi}