|
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"
|
|
|
|
|
you work here??? 
_________________________
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....
|
|
|
|
|
yes, as a commit analyst.
|
|
|
|
|
I maintain a change log, reverse chron, at the top of every source code file (including scripts, modules, headers, etc.). Every time I touch a module, there's a change notice in the log, with date/time, my ID, what computer I did it on, and a description of the change. I have Emacs key bindings that pick up all of the demographic and date/time info from environment variables and the OS, format the notice, and position me for the description; that makes it pretty painless.
|
|
|
|
|
Ennis Ray Lynch, Jr. wrote: 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.
When I first started using Subversion as part of a team working on Java webapps (zzZZzz  ) I'd commit with reasonably descriptive messages like "MonkeyRequestHandler no longer throws an exception on empty event lists. Also MonkeyModel now fully parses Bananas" etc. Then I saw that most of the commits from the other developers were like "Changed some stuff" or "..." or "Updates"
|
|
|
|
|
And, it works very well if I don't say so my self
|
|
|
|
|
Yes, in some cases. I don't write comments for all the methods, fields and classes. Whenever it is require and when it says "Why" at that time I write comments.
I have seen some code files where comments are more than the codes. This is not good at all. Your code should tell clearly why you are doing this. In some scenarios, it is difficult to understand why we need to write the code. In that case, I write comments.
Don't forget to Click on [Vote] and [Good Answer] on the posts that helped you.
Regards - Kunal Chowdhury | Software Developer | Chennai | India | My Blog | My Tweets | Silverlight Tutorial
|
|
|
|
|
Yeah true fact. You can understand your code & the purpose.. also your team mates(most of), but some people... so the comments will help other people to understand the code & purpose when you off & not able to contact you.
|
|
|
|
|
I find something useful to say about virtually every line that isn't obvious from the code. Along with block comments as preambles to sections of code, it builds a narrative that allows "reading" the code via the comments to get to the section you're interested in. I've been doing that for over 40 years of coding, and I still deal with code I wrote over 20 years ago. I _never_ spend significant time figuring out what that code is doing, and neither does anyone else who has occasion to read the code.
The key, IMHO, is to instill the habit down into your very soul, so it's like breathing. If I were to write 5 lines of code without any comments, I would start feeling distress.
And, BTW, one thing that helps with very nested code is for each block "end" statement or curly brace to have a comment stating what's being ended. I have Emacs key bindings that do this pretty automatically.
|
|
|
|
|
Documenting your code is good but not all the lines. Putting comments for each line is not a very good practice. Not only it increases the length of the file but also increases visibility of the actual code. As I mentioned, I found one such code file where no. of comments were more than no. of codes.
Just for an example:
int i = 0;
string tempValue = string.Empty;
tempValue = string.Format("{0} {1}", firstName, lastName);
I don't think, it's a very good idea to comment each & every line. You can understand what you are doing here. You should comment those lines of code where it is little bit difficult to understand and there you should tell why you are doing this rather than what you are doing.
You should do documentation for all the public methods so that, if you are calling it externally from the assembly reference, you should know what you are doing there.
Don't forget to Click on [Vote] and [Good Answer] on the posts that helped you.
Regards - Kunal Chowdhury | Software Developer | Chennai | India | My Blog | My Tweets | Silverlight Tutorial
|
|
|
|
|
I strongly disagree. The examples you gave are silly; if I were the programming manager who saw those, I would have a serious talk with the coder about making comments meaningful, instead of just repeating what the code says. Some notes about the examples:
1. "i" is a horrible variable name except for very local, very limited use. The variable name should say what the variable does.
2. "int" was a bad idea in C/C++. You don't know from one day to the next what size it is.
3. We don't use native data types anyway; we typedef them all in a common header, to protect ourselves from compilers and platform shifts.
4. We break lines, with a "continuation" indent of 2, if they would otherwise protrude into the on-line tabbed comment area.
Here's what that code would look like in our shop:
Ulong bugcntr = 0; //init: no bugs seen yet
String tempValue = String.empty; //init: no temp value yet
// Save first and last names for use later, in a format we can easily
// detokenize:
tempValue = string.Format("{0} {1}",
firstName, lastName); //save names as temp
(Note: The comments are tabbed properly; somehow the blog display is messing them up.)
I have created, and currently maintain and enhance, a software product comprising over 1/2 million code lines of C, in over 2,700 modules and over 2,400 header files. It is all commented to the quality level shown above. Some of it is over 25 years old, but when I go back to it I spend NO time figuring it out. It is very complex and sophisticated code, yet I spend very little time debugging; the majority of my coding time is adding features. The heavy commenting in the code is what makes that possible.
|
|
|
|
|
I agree your point. It is not a good way to comment where I am telling directly what my code is doing. If you read my post, I clearly mentioned that, you must comment why you are writing the code. Why has more value than What. By reading the code, it is easy to understand the question "what" (not all case!!!) but why? Yes, this has more power to the code. I am not going to a war of intending the code here or data types used for C/C++/C#. The above code was just a small example of what I saw earlier in some code file (not the exact line/sentence).
Don't forget to Click on [Vote] and [Good Answer] on the posts that helped you.
Regards - Kunal Chowdhury | Software Developer | Chennai | India | My Blog | My Tweets | Silverlight Tutorial
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
