-   Programming (
-   -   How to comment effectively? Any tips? (

pwc101 06-01-2007 01:18 PM

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:


# here is my script
some commands

# another comment
more commands


Fair enough - easy to read, no harm done.

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":



# here is my script
some commands


# another comment
more commands



but these are a little ugly and not especially elegant.

How do you comment your scripts?

Do I need to get a life? ;)

puffinman 06-01-2007 01:32 PM

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.

kshkid 06-01-2007 01:45 PM



# here is my script
some commands

# another comment
more commands


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 :

Tux-Slack 06-01-2007 01:52 PM

Here's how I do mine:

# Short description of the script

variable settings          # Comment on each variable setting, what is what aso

# Then comment just what the script does
set of commands that do something, ie check if runing as root

# Another comment on what script does with next set of commands
more commands


I've never done this in a bash script
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

indienick 06-01-2007 04:32 PM

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.

PTrenholme 06-01-2007 06:21 PM

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.")

pwc101 06-02-2007 03:23 AM

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 :)

makyo 06-02-2007 07:20 AM


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

Title: Perl Best Practices
Subtitle: Standards and Styles for Developing Maintainable Code
Author: Damian Conway
Date: 2005
Publisher: O'Reilly
ISBN: 0596001738
Pages: 500
Categories: perl, standard, development, scripting, programming

Title: Code Complete
Subtitle: A Practical Handbook of Software Constriction
Author: S McConnell
Edition: 2 edition (June 2004)
Date: 2004
Publisher: Microsoft Press
ISBN: 0735619670
Pages: 960
Categories: development, building, programming, coding, tools
Comments: 5 (of 5) stars, Amazon, 70 reviews, 2007.06.
Comments: SM writes a blog at

Title: Classic Shell Scripting
Subtitle: Hidden Commands that Unlock the Power of Unix
Author: A Robbins, N Beebe
First Edition: May 2005
Publisher: O'Reilly
ISBN 10: 0-596-00595-4
Pages: 558
Categories:  scripting, shell, programming

jiml8 06-03-2007 09:16 AM

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.

Randux 06-03-2007 04:04 PM

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.

bigearsbilly 06-04-2007 02:55 AM

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.

taylor_venable 06-04-2007 09:58 PM

I agree completely with everything said so far. A few random comments, based on the last post:

Originally Posted by bigearsbilly
3. explain expected input data formats

This is extremely important in dynamically typed languages. Make sure either to indicate it's type (e.g. "must be a string") or some condition the type must satisfy (e.g. "must respond to '+' message" or "must satisfy 'buffer-or-string-p'").


Originally Posted by bigearsbilly
4. give examples of use even better with associated dummy data files maybe.

Totally agree. Nothing is more useful when (re)visiting a strange function than seeing something like:

zip :: [a] -> [a] -> [(a, a)]
Pairs elements of two arrays.
EXAMPLE: zip [1,2,3] [4,5,6] = [(1,4), (2,5), (3,6)]

jtshaw 06-04-2007 10:16 PM


Originally Posted by indienick
* 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.

Along those lines... a wise man once said:

"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).

bigearsbilly 06-05-2007 02:41 AM

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 09:35 PM.