But for the occasional case where I want to put some comment in my code, these tips will be very helpfull indeed.

function ProcessRequest(Player p, Action a) { // Step 1. Validate request // Step 2. Create local variables // Step 3. Collect object rules for evaluation // Step 4. Perform action on Player object ……. Posted by Joshua Olson · 28 days ago · Link It’s my favorite method when I create functions, BUT, there is a drawback in this method, sometimes when you maintain the fucntion, you must change the inside logic, the step sequence will be crashed, for example, the step3 is removed, then you should modifiy the comments to maintain the readability. Maybe you should go through all the function just to change the step index in the comment, you will hate yourself for the over comment:)

and the article pointed out by Alex (history of hungarian notation) http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnvs600/html/HungaNotat.asp

when used as intended it can be very useful. When used to show that an int is an int - well, its a waste of time.

As a long-time coder (and occasional PHB :-)), it’s my experience that any non-trivial code needs commenting. Non-trivial in this sense is any code used for more than a couple of months by more than a couple of people or code that ever serves more than its original narrow purpose.

I worked as a Big-5 consultant for a number of years on a project for a large US state gov’t agency. In that time, the code had (I counted!) 47 sets of hands in it. Commenting was critical to help us understand a) what the various modules were supposed to do or how they were intended to do it, b) how badly the writer had misinterpreted the voluminous and detailed specs and c) making decisions about refactoring interfaces for a move from client-server to web-based (the comments helped indicate dependencies).

My current position is the 6th or 7th developer on a commercial product that’s been around in one form or another for 10+years. Comments are important to me here b/c I was not around for the design or implementation decisions for the framework I’m maintaining/extending.

To those who say ‘well-writen code needs no comments’ I say ‘read your own crap after a couple of years or a dozen other projects’. Unless you are lucky enough to be able to walk away from all not-new-development work, sooner or later you will have to either pick up someone else’s leavings or you’ll have a client that wants your months- or years-old code modified. At that point, having to read code to see what’s going on will be an expensive indulgence, either in billable hours or time with the family or whatever your value proposition is.

I think comments should be added judiciously so that whoever changes that code in the future would be more likely to update the comments as well.

I don’t actually code, but often a programer or their manager will print out a section of code for troubleshooting/review. Having the code properly commented - in a manner similar to what you describe - greatly increases our efficiency as we can become familiar with the logic quickly and leverage the problem solving abilities of some of our non-programmers. Utilizing proper commenting is the only way that we can effectively do this across platforms and languages. Good read. I’m going to forward to my staff as a helpful link.

Great article. I’ve been writing SW code and HW description code (Verilog and VHDL) for years and I have adopted a style that I try to use on all my source files (with variations based on language rules).

Basically they boils down to:

(1) File header AND footer. The footer is basically and EOF . But I find that it helps greatly, esp when looking at printouts. Header and footer are framed with a row of “=” 72 characters in length.

The header names the file, describes the contents and the purpose of the contents (for example interface module for the design of ASIC XYZ, database class used in the processor model QWERTY etc) any special design considerations, references to design specifications that might be of interest etc. Finally the header ends with author name, copyright and that PHB-stuff. (Yes, I do sign all my work.)

(2) Framed comments preceeds functions/processes. comments. That is, all functions/processes are preceeded by a comment that describes the intended functionality, pre- and post-conditions, specific code details etc. These comments are framed with a row of “-” 68 chars in length.

(3) Whitespaces. I use blank lines to separate chunks of code within a function, between functions. I use the cosistently with, for example, always two (2) lines between functions.

(3) Comments within functions preceeds a chunk of code. The comments explains the purpose and any specific detail - reasons for doing a certain thing. (If needed.)

(4) Use different comment types for comments and code debug. In C/C++ I use “//” for all code comments. This allows med to use “/* .. */” to comment out blocks of code. Also I can easily spot is a comment is for documentation or not. Languages that don’t support (at least) two types of comments are quite annoying to work with.

(5) Code sections are named and divided. I try to layout the contents of the code in a file in a common way. Normally something like:

(I) Includes and defines (II) Module interface (if any) (III) Any global variables (common in HW) (IV) Storage element allocation and handling (V) Data flow/manipulation code (fun/process) (VI) Control flow code

These sections are are declared and framed off using a one line section declaration framed with upper- and lowe rows of “-” 72 chars long.

Note that I use 72 chars for headers and sections, and 68 chars for function headers. This allows me to visually see where section ends.

A brief note on {} (or BEGIN-END). They IMHO should be alligned together. For example

void kalle() { do_something(); }

And when it comes to intendation. Any good editor (i.e. Emacs) allows you to set that it actually produces n number of space characters when you press TAB. Intendation shall be done using space, but you should not need to actually hit that bar that many times - it opens up for errors.

/Joachim S - ASIC designer at large