How to comment effectively? Any tips?
I'm just starting bash scripting in earnest, and one of the things I've always had trouble with is finding a commenting style that suits me. At first, my scripts were short, so commenting style wasn't really an issue. It'd be something like this:
Now though, some of my scripts are getting long, they've got functions, different sections which do different things, so that style of commenting doesn't work any more. I've tried subdividing by setting "barriers":
How do you comment your scripts?
Do I need to get a life? ;)
You might try looking around your system for lengthy bash scripts and see how "pros" do it. Init scripts (look in /etc/init.d) are all bash, pretty long, and have tons of comments.
Partially the above is the style that we have been following
In addition to that if its a function definition, we would have it as,
##### function name #####
# input :
# output :
# description :
Here's how I do mine:
But in "real" programing as in C or C++ I allways comment the same way as above and when I strike an error I put it in a comment so I don't forget about it.
Use comments for usefull stuff.
Try to explain what each step does. Usually I comment whole functions. I.e. if I have a function that connects to the database, gets some info from it to variable or variables and returns it back, the comment would look something like this:
* Connect to Database and
* search for something
My commenting style came about for when I was learning Common LISP:
* When I assign a variable its value, I don't comment it (unless it is of some serious importance); the variable's name should make it evident as to its purpose.
* When it comes to big blocks of code (methods, functions, procedure, constructors, general methods, etc.) I make a big comment block above the code block to explain what I'm doing - I found that if I comment each line, or pepper comments throughout the code block, it made the readability suffer.
Those are the basic guidelines I follow. I find EOL (end of line) commenting to be bothersome.
In the "spirit" of UNIX/Linux, and "function based" languages, consider breaking your long scripts into either (short) functions or separate scripts, each small, easily commented, and limited to a single action. (Some people refer to that style as "object oriented" or "modular.")
Thanks for all the suggestions. I've removed my ugly barriers, put in a header which describes the whole script, who wrote it etc, and I've put in function definitions. It now looks a lot more readable, but without being too confusing.
Is there a standard way of doing this, or is it just left up to the developer? Does RedHat have a particular style whereas Debian has another? Just curious :)
The first two books below have sections on commenting. The third has to do with shell scripting, plus a little awk. I would not buy these books only for the advice on commenting (in fact the 3rd has little to say about it). They are good references, so if you needed them for other purposes, you'd get a bonus for the comments section ... cheers, makyo
Use descriptive variable names, and be consistent in your variable naming conventions, and employ a consistent indentation mechanism. Then you don't need to do much commenting; the intent and the functional grouping is obvious from the lines of code.
You then reserve comments for things that are not obvious - and you decide what is/is not obvious by considering how you, yourself will view the code if you have to review and change it a year from now - long after you've forgotten what you've done. You also commonly would make a "header comment" above critical subroutines, defining allowed states, input variables, and their ranges.
Thus, when you identify a bug in your language and an appropriate workaround that will look strange in the code, you put a comment: "this next operation takes care of undocumented behavior in library function foo(), where it does this... when we expect it to do that..."
I usually will place a comment after a right brace if the block of code enclosed in the braces is more than a couple of lines long, and my comment will reflect the conditional that leads to the open brace. This way I know what this brace should relate to without trusting my editor to tell me, and without depending on indents. Helps a lot with debugging.
Over-commenting leads to visual clutter and detracts from comprehensibility. Appropriate commenting is a really big help.
I agree with indienick and jiml8 the content is what you should focus on. It doesn't help to comment lines that are obvious like setting a variable unless something needs to be explained.
The first part of doing comments properly is choosing meaningful names and doing it consistently. Every program should be as close to self-commenting as possible, that makes it readable. Write comments whilst coding, if you plan to just write the code quickly and go back later and add comments you'll never make time for it.
Write a narrative for each logical section of code, what you're trying to accomplish, what you're thinking, and why you made certain decisions. All this will help not only a newcomer but you'll be surprised how much you forget when you come back to your own programs years later. If there are any aspects you weren't able to cater for in the code, note the deficiencies so you or someone else will know what has to be added later. Add whatever logic necessary to protect against impossible conditions and issue a meaningful message so that your program doesn't simply crash without giving anyone an idea why.
I would say, as someone with experience of wondering what the hell
I was doing 6 months ago...
if it's a reasonably complex system I put most of the
comments at the top so you can get a quick idea before reading the code.
1. explain briefly what the thingy does,
2. explain more in depth how it does it
3. explain expected input data formats
4. give examples of use even better with associated dummy data files maybe.
Each function maybe a brief description where neccessary.
In the code itself just snippets on the very tricky stuff.
I agree completely with everything said so far. A few random comments, based on the last post:
zip :: [a] -> [a] -> [(a, a)]
Pairs elements of two arrays.
EXAMPLE: zip [1,2,3] [4,5,6] = [(1,4), (2,5), (3,6)]
"Comments are good, but there is also a danger of over-commenting. NEVER
try to explain HOW your code works in a comment: it's much better to
write the code so that the _working_ is obvious, and it's a waste of
time to explain badly written code.
Generally, you want your comments to tell WHAT your code does, not HOW.
Also, try to avoid putting comments inside a function body: if the
function is so complex that you need to separately comment parts of it,
you should probably go back to chapter 6 for a while. You can make
small comments to note or warn about something particularly clever (or
ugly), but try to avoid excess. Instead, put the comments at the head
of the function, telling people what it does, and possibly WHY it does
That is from the CodingStyle document in the Linux Kernel documentation.
For those of you that don't want to dig it out.. Chapter 6 discusses how functions should be short and sweet and do only one thing (and do it well).
can't agree more.
as you progress as a programmer your code becomes simpler and less flashy.
when I was younger I would do complicated arrays of pointers to functions for example,
where now I would use a nice simple switch.
It's important to keep it as clean and neat as possible because no doubt some poor bugger
may have to come along and maintain what you did at some point. (even worse it may be you)
|All times are GMT -5. The time now is 11:02 PM.|