|
>Such projects typically have system documentation explaining what each (much smaller) component does.
Hollow laughter
It would be awfully nice if everyone else documented as helpfully as we do, but they don't! As a matter of fact I have to produce a lot of documentation - defence projects, you know - but the real low-down stuff - why I used small int instead of int - does not need to be read by the customer, and QS can get the wrong idea if they see "use small int to avoid access violation". Also we keep official documentation to a minimum, because it's all under version control, and as you rightly say, every memo and every email swamps the useful stuff.
Comments are for me and for future maintainers. Someday you may have to maintain my code and you will be glad of it!
------------------<;,><-------------------
|
|
|
|
|
I always trust documentation within the code more than any other form of documentation. Why?
A) Typically 'system/project documentation' is more related to end-user functional/workflow aspects and does not match technical methodology/coding used to actually accomplish the detailed processes/tasks.
B) Documenting within code verses within a seperate document tends to match the code over the long term much better. It tends to be much more accurate & timely because it is written as the code is written/maintained. As people stick their fingers into an application, you can bet someone (all of them?) will not have (take) the time to update a second 'documentation only' file (ie: Patches/fixes developed & implemented at 3 am tend not to be documented at all except perhaps via archived e-mails, etc).
C) After 40+ years as a developer, I've learned the hard way that I can't depend on any documentation to actually match the code. But the documentation within the code tends to be the closest to the logic used that I'm going to find and it will generally help me get into the mindset of the coder faster (ie: what the heck was this guy thinking when he wrote this peice of s**t ... whoops, I wrote that junk code two years & 4 projects ago and know better (now)).
GoodTime Charlie, VA
|
|
|
|
|
At least for the signal processing code I work on I have to disagree.
The operations are the same more or less, some simple to mid-sized formulas, some scaling, some FFT's, some curve fitting, some filling / sparsing spectra, some vanilla filters. Still, when stringing half a dozen FFT's together to get from A to B the purpose isn't obvious, even if you understand the individual elements.
|
|
|
|
|
If you give appropriate names to functions, structures, variables, etc. you can avoid commenting most of the time.
36. When you surround an army, leave an outlet free.
...
Do not press a desperate foe too hard.
SUN-TZU - Art of War
|
|
|
|
|
"most of the time" is not "all the time"... while I agree that appropiate names are useful, I think that sometimes there's no option but to comment code. Sometimes good names are just not enough...
Cheers!
|
|
|
|
|
Well, behold our mighty brain. Because each person had different mind I think that's why we need to comment our codes 
|
|
|
|
|
I just agree to Fernando A. Gomez F. and savire.
StyleCop will be your friend 
|
|
|
|
|
Let your code tell you how, and the comments say what it's supposed to do.
Add as applicable, but not so much as to make reading difficult. Then again, always know your audience. If you're writing a tutorial, comment copiously.
As the programs in the Matrix would know... Those without purpose are deleted.
Same should go to comments.
|
|
|
|
|
I usually think that the name of a method should tell the "what", and the method body the "how", there is just the "why" missing. Although, I've found myself documenting the what an the how when needed, and that has been implementing some numerical methods (http://en.wikipedia.org/wiki/Numerical_analysis[^]) in particular for hashing (I only maintain two of those).
There are other uses for comments, one is keeping tasks and status of the code. I use "ToDo", "Missing" and "InProgress" to tag me tasks. Other is skipping lines of code for test propouses. And I use "Empty" to tell that a code block is empty because it's meant to be empty not because I forgot to write it (Happens often in constructors and virtual methods).
[wrote thinking of Java, C# and VB, this will not apply for most not OO languages]
|
|
|
|
|
Probably some people answer as they wish to do rather they actually do ...
36. When you surround an army, leave an outlet free.
...
Do not press a desperate foe too hard.
SUN-TZU - Art of War
|
|
|
|
|
I cant get enough comments. comments are what keeps me sane when relearning what was done on projects long past. I have found I cant remember what my own code is doing if i'm not working with it constantly, so my code has comments galore.
|
|
|
|
|
Yes. The older I get, the less I remember from one week to the next. And the older the code gets I have to maintain. Without comments I am lost.
Since we produce safety critical code QS uses tools to count how many comments we write. There are standard headers for files and methods so it's easy to get started.
It is also helpful to write the date you changed something, then you can refer back to logbooks and emails for a better idea of what was going on. And if you change someone else's code, put your name in too.
I have written silly comments in the past, for example:
//This is a miserable piece of hackwork and I am ashamed of it
//I don't know why this works. Don't change it
//This is a waste of time but "project management" wanted it
------------------<;,><-------------------
|
|
|
|
|
when it comes to commenting i also comment everything. especially global or scoped variables whose purpose may look obscure. Nothing to do with age, or anything. just something that was drilled into me in college.
commenting your code is king. specially if another programmer looks at the code they can easily tell what function/method/ect .. does what, and if the comments are done right, they should provide a quick overview of the last couple of revisions to that chunk of code.
This information is invaluable to programmers looking at someone else's code for the first time.
|
|
|
|
|
Teaching Assistant, not any other acronym....
way back in college I was programming in Pascal (yeah, yeah, no comments about they had computers back then  ), I was always being counted off in programming for lack of comments. Now, mind you, I didn't consider myself lacking in comments at all. I used header comments, documented inputs, outputs, intent and any obscure logic (like my 5D storage structure for the final project). Since it was the only thing I was ever deducted for (except the time I found a different, correct, answer than the teacher), I was a bit annoyed by the mark-offs.... So I decided to solve the problem ad absurdem, I was going to over-document the whole thing.
The next assignment required aproximately 100 lines of code and the total including comments was nearly 250 lines of code. As well as every single statement having its own line documentation. I documented everything. even endif's had documentation saying endif and what it was, every if had a reason, every variable had a documentation line, every single line had a documentation line....
It was the only time I got "good documentation" on the grade.... 
_________________________
John Andrew Holmes "It is well to remember that the entire universe, with one trifling exception, is composed of others."
Shhhhh.... I am not really here. I am a figment of your imagination.... I am still in my cave so this must be an illusion....
|
|
|
|
|
On a similar vane, I had a professor count off points on my assignments because I used "proper java style" ie, my curly braces were not on a new line. He took me aside and told me that if I didn't conform I wouldn't make higher than a B in his class. I told him if he wanted to give me a B for a correct program that was his problem; I got an A. I later got to be his T.A., that was fun. It was the first time in my life I found out how bad some programmers are!
|
|
|
|
|
I remember in college the compiler counted comments and gave some sort of output to help the TA grade us...
|
|
|
|
|
|
Lol you make me remember my old PASCAL codes with inline assembly codes which i wrote horizontally until it goes around 100 lines or more, haha.
|
|
|
|
|
Have you ever looked back at a comment you wrote 6 months ago and said, "What they heck was I thinking?"
|
|
|
|
|
That's when I wish I had commented the comment.
|
|
|
|
|
|
That might have happened many years ago when I was a newbie, but not for a long time. I have taught myself to comment not only for others, but for my future self. One key is a good English abbreviation system for on-line comments, to keep them short but easy to read.
|
|
|
|
|
That more people would comment there source control check-ins. When there is a bug in an application and you an scan a specific history for a specific type of change it makes identifying the error so much easier.
I also have a bad habit of diffing good developers versions with bad developers versions to more quickly identify bugs as well :p
|
|
|
|
|
Ennis Ray Lynch, Jr. wrote: That more people would comment there source control check-ins. When there is a bug in an application and you an scan a specific history for a specific type of change it makes identifying the error so much easier.
I also have a bad habit of diffing good developers versions with bad developers versions to more quickly identify bugs as well :p
Ditto....
In on of our long distant versions of RAGE, we had a header that documented each dotted version change and what was changed. Since it was not at the time version controlled it was the best way to keep that. When I finally convinced folks with the help of a new programmer that we needed version control, we kept that header too, as well as documenting the checkins... Then our new guy left, and we sought another new guy.... That person removed the header because it was redundant, then when another new programmer stopped documenting checkins and others found out he was getting away with it, things stopped being updated and now we have nothing.... Now I have to remove the bad habits that were built up....
_________________________
John Andrew Holmes "It is well to remember that the entire universe, with one trifling exception, is composed of others."
Shhhhh.... I am not really here. I am a figment of your imagination.... I am still in my cave so this must be an illusion....
|
|
|
|
|
"fixed bug"
"added that feature"
"no comment"
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
