Code Documentation

Yes, Comments are good. Usually when I do not comment, I regret it a month later or something


Edited by - mr BiCEPS on November 9, 2000 7:22:13 PM

Try leaving your code for 6 months and come back to it.. then decide whether if it is worth it..

I have written very useful and functional libraries which after time are very difficult to use (meaning they don''t get used) becasue I failed to write a reference document to them.

If you want to present yourself as a professional programmer you should both comment and document your program. While many may argue with me the proper place for documentation is in a seperate document. Most comments should be one sentence of one line or occasionally two. Anything more than that and you should be refering them to a section of the documentation instead. That is the ideal world. Within the real world documentation often gets lost or a person spends six months figuring out what they would have learned in a few hours reading the documentation. So to deal with that reality some documentation should be placed into the code. A few lines to a paragraph at the start of a function and perhaps as much of a page for the program. The goal isn''t to duplicate the documentation, but rather to remind people of what they read in the documentation. If the documentation is lost you are just trying to minimize the damage not make it irrelavent.

Personally within the code all I''m trying to do is provide a memory aid. I feel that if there are ten lines of code that do some cohesive function then if a person changing any one of those lines then they need to read all of that code. I am not interested in making it easy for them to change one of ten interdependant lines of code without understanding how they work together and for that they need to read the code. If they are not changing that code and their changes have nothing to do with it then there is no need to force them to read it to know that. If their change is related they need to understand it, but they have to understand something else as well. That could be a lot so you provide a memory aid so that once they read the code they can just say "oh yeah, that''s what this section does" after that. I am very much against making a person believe they know what they are doing when they don''t, but neither am I big on making them have a good memory when it comes to understanding a large program.

When it comes to doing it for yourself it is a differant story. First is whether you need it or not. Don''t make the mistake of thinking that because you are not challenging yourself that you don''t need the comments. If the programs you are writing are truly difficult for you and you don''t find any benefit from the comments you are writing then you may not need them. I don''t use comments, but that is because I run a program I''m working on about every five or ten lines of code. Rather than counting on comments to help me remember I use the debugger. Rather than worrying about whether I was supposed to add or subtract I run it and see if it is right. I code most of my classes in a program dedicated to testing the class and then move it into the program I''m actually working on when I''m sure it is right. They use to kid me at work about being on build 3 or 4 thousand on the first release. So I know why I don''t need comments in a program. You need to be sure of why you don''t need them.

A second issue is whether you can be sure you are the only one that will be using the code because it is a royal pain to write the comments after the fact. I''ve done it that way and trust me when I say it is far easier to write as you code. I rearrange and reduce a lot of code as well as changing variable names to better reflect their purpose. If I know I''m going to have to comment it then I comment sections as I finish them. I don''t know what comments are actually needed until I see the final version of the routine. It isn''t any big deal one routine at a time, but when you make a mistake and find you have 50,000 lines to comment it is a differant story. A month or two of coding can turn into a month or two of commenting.

A third issue is whether you need any practice at commenting. I''ve written over 2,000 pages of program documentation and most likely well over 100,000 lines of comments. When it was assembler with eight character names every line was commented. I have plenty of practice. Well, I could use some more practice with technical writing, but if I''m going to comment a program I know how I''m going to do that. I have a style that I use and I generally don''t get any complaints about it. When I don''t comment that is an entirely differant story which I can only refer you back to the point in the previous paragraph to explain how that happens.

When it comes to your career you want to comment. You want to present as professional a front as possible. I don''t care much about dressing for success, but I care a great deal if people feel my work is professionally done. Comments are not the most important thing. As far as I''m concerned they fall far down the totem pole but it is a defacto standard. If you want to do a professional job then you don''t say this is low on the list of important items so I''m not going to do it. Instead you say it is on the list and I''m going to do it. Writing the code is more important than testing it, but you had best test it. Not completing everything on the list is something to apologize for. Personally I''m happier with a good program with no comments than a bad one with good comments, but even though I don''t use comments I''m going to judge the good program with good comments to be the more professional program. I''m also going to care about a great many other things, but all other things being equal you lose for not commenting.

Hehe, doesn''t that surprise everyone. My arguements before were only about whether I find utility in comments and whether I felt it was worth while to do it for my own benefit. I didn''t argue they were of no benefit to anyone else If anyone but me is going to see the code then I comment, just the same as if someone else is going to be running it then I make it far more idiot proof than I do for my own benefit.