LinuxQuestions.org
Register a domain and help support LQ
Go Back   LinuxQuestions.org > Forums > Non-*NIX Forums > Programming
User Name
Password
Programming This forum is for all programming questions.
The question does not have to be directly related to Linux and any language is fair game.

Notices

Reply
 
Search this Thread
Old 06-01-2007, 01:18 PM   #1
pwc101
Senior Member
 
Registered: Oct 2005
Location: UK
Distribution: Slackware
Posts: 1,846

Rep: Reputation: 128Reputation: 128
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:
Code:
#!/bin/bash

# here is my script
some commands

# another comment
more commands

exit0
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":
Code:
#!/bin/bash

##----------------------------------------------------------------------------##

# here is my script
some commands

##----------------------------------------------------------------------------##

# another comment
more commands

##----------------------------------------------------------------------------##

exit0
but these are a little ugly and not especially elegant.

How do you comment your scripts?

Do I need to get a life?
 
Old 06-01-2007, 01:32 PM   #2
puffinman
Member
 
Registered: Jan 2005
Location: Atlanta, GA
Distribution: Gentoo, Slackware
Posts: 217

Rep: Reputation: 30
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.
 
Old 06-01-2007, 01:45 PM   #3
kshkid
Member
 
Registered: Dec 2005
Distribution: RHEL3, FC3
Posts: 383

Rep: Reputation: 30
Quote:
#!/bin/bash

# here is my script
some commands

# another comment
more commands

exit0

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 :
##########################
 
Old 06-01-2007, 01:52 PM   #4
Tux-Slack
Member
 
Registered: Nov 2006
Location: Slovenia
Distribution: Slackware 13.37
Posts: 511

Rep: Reputation: 36
Here's how I do mine:
Code:
#!/bin/bash
#
# 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

etc
etc
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
*/
 
Old 06-01-2007, 04:32 PM   #5
indienick
Senior Member
 
Registered: Dec 2005
Location: London, ON, Canada
Distribution: Arch, Ubuntu, Slackware, OpenBSD, FreeBSD
Posts: 1,853

Rep: Reputation: 65
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.
 
Old 06-01-2007, 06:21 PM   #6
PTrenholme
Senior Member
 
Registered: Dec 2004
Location: Olympia, WA, USA
Distribution: Fedora, (K)Ubuntu
Posts: 4,147

Rep: Reputation: 330Reputation: 330Reputation: 330Reputation: 330
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.")
 
Old 06-02-2007, 03:23 AM   #7
pwc101
Senior Member
 
Registered: Oct 2005
Location: UK
Distribution: Slackware
Posts: 1,846

Original Poster
Rep: Reputation: 128Reputation: 128
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
 
Old 06-02-2007, 07:20 AM   #8
makyo
Member
 
Registered: Aug 2006
Location: Saint Paul, MN, USA
Distribution: {Free,Open}BSD, CentOS, Debian, Fedora, Solaris, SuSE
Posts: 718

Rep: Reputation: 72
Hi.

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
Code:
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 http://blogs.construx.com/blogs/stevemcc/default.aspx

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
 
Old 06-03-2007, 09:16 AM   #9
jiml8
Senior Member
 
Registered: Sep 2003
Posts: 3,171

Rep: Reputation: 114Reputation: 114
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.
 
Old 06-03-2007, 04:04 PM   #10
Randux
Senior Member
 
Registered: Feb 2006
Location: Siberia
Distribution: Slackware & Slamd64. What else is there?
Posts: 1,705

Rep: Reputation: 54
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.

Last edited by Randux; 06-03-2007 at 04:08 PM.
 
Old 06-04-2007, 02:55 AM   #11
bigearsbilly
Senior Member
 
Registered: Mar 2004
Location: england
Distribution: FreeBSD, Debian, Mint, Puppy
Posts: 3,276

Rep: Reputation: 170Reputation: 170
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.
 
Old 06-04-2007, 09:58 PM   #12
taylor_venable
Member
 
Registered: Jun 2005
Location: Indiana, USA
Distribution: OpenBSD, Ubuntu
Posts: 892

Rep: Reputation: 40
I agree completely with everything said so far. A few random comments, based on the last post:
Quote:
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'").

Quote:
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)]
 
Old 06-04-2007, 10:16 PM   #13
jtshaw
Senior Member
 
Registered: Nov 2000
Location: Seattle, WA USA
Distribution: Ubuntu @ Home, RHEL @ Work
Posts: 3,892
Blog Entries: 1

Rep: Reputation: 65
Quote:
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
it."

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).
 
Old 06-05-2007, 02:41 AM   #14
bigearsbilly
Senior Member
 
Registered: Mar 2004
Location: england
Distribution: FreeBSD, Debian, Mint, Puppy
Posts: 3,276

Rep: Reputation: 170Reputation: 170
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)

:-)
 
  


Reply


Thread Tools Search this Thread
Search this Thread:

Advanced Search

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is Off
HTML code is Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
LXer: UGS' Teamcenter 2005 Delivers Comprehensive PLM Offering to Effectively Address Embedded Software Management for Mechatronics LXer Syndicated Linux News 0 06-21-2006 04:54 AM
Can't use the Scroll Button effectively in Linux duffmckagan Linux - Software 1 06-08-2005 05:13 AM
Protect File: how to monitor directory effectively? iclinux Programming 1 12-30-2004 03:02 AM
comment wardrazer *BSD 2 07-14-2003 08:22 AM
using autofs to effectively symlink to an existing filesystem unsteady Linux - General 0 04-12-2001 09:10 AM


All times are GMT -5. The time now is 06:09 PM.

Main Menu
My LQ
Write for LQ
LinuxQuestions.org is looking for people interested in writing Editorials, Articles, Reviews, and more. If you'd like to contribute content, let us know.
Main Menu
Syndicate
RSS1  Latest Threads
RSS1  LQ News
Twitter: @linuxquestions
identi.ca: @linuxquestions
Facebook: linuxquestions Google+: linuxquestions
Open Source Consulting | Domain Registration