|
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
|
|
|
|
|
I comment quite everything but I can't say I actually do it.
I use GhostDoc... Right-Click on top of "it" and hit Comment!
Few times I actually change what it generates and to be honest what it generates add nothing to whoever may be using "it".
Bottom lime is, I tend to use meaningful names and try to keep them under their scope so you can easily get what you want.
The most important is to specify naming conventions, and be very rigid following them. This makes it easy to know what and where to find what we need withing the intellisence.
For me, comments are more helpful withing a method to add some sense to some piece of code that needs more than just that in front of you to understand.
|
|
|
|
|
lol. GhostDoc is the best.
|
|
|
|
|
on purpose?
|
|
|
|
|
I've heard it's been said
that that is the only way
most of us can keep our jobs . . .
/xml> "The difference between genius and stupidity is that genius has its limits." - Albert Einstein
| "As far as we know, our computer has never had an undetected error." - Weisert
| "If you are searching for perfection in others, then you seek dissappointment. If you are searching for perfection in yourself, then you seek failure." - Balboos HaGadol Mar 2010
|
|
|
|
|
|
I know you were being facetious, but seriously, this is sometimes done. IMHO it is professional malpractice of the worst sort and should result in being summarily fired. If it's done to keep the coder's job, it should have exactly the opposite effect.
BTW, this should be caught in code review.
As a separate issue, there is sometimes the need to obfuscate the code, for IP reasons. There are code tools that can do this reversibly (I am the author of one).
|
|
|
|
|
But they must be helluva productive, having written most of the code I got to see in my career.
|
|
|
|
|
They all work for Sage.
------------------------------------
I will never again mention that I was the poster of the One Millionth Lounge Post, nor that it was complete drivel. Dalek Dave
|
|
|
|
|
And I doubt they left comment in this forum!
Marc
|
|
|
|
|
I comment on code where I think "Hmmm in 6 months when I look at this again, will I know what I am looking at?"
So tend to block comment rather than every line, and tail-comment on a complex or unusual line of code.
(Also, why is it possible to select "I don't Comment" and any other comment selection? Mutual Exclusivity!)
------------------------------------
I will never again mention that I was the poster of the One Millionth Lounge Post, nor that it was complete drivel. Dalek Dave
|
|
|
|
|
Dalek Dave wrote: "Hmmm in 6 months when I look at this again, will I know what I am looking at?"
Heck, I can't even remember what code I did yesterday... 
Nothing more embarrassing than asking all the collegues: "What idiot did this piece of code?" just to get the answer "You did!"
|
|
|
|
|
I mentioned in a thread in the lounge a little while ago about seeing the horrors of a 16x Nested IF...THEN...ELSE statement.
It was one of them slowly increasing over time things that got out of hand, so I rewrote it as a CASE, but I was embarrassed about that one!
------------------------------------
I will never again mention that I was the poster of the One Millionth Lounge Post, nor that it was complete drivel. Dalek Dave
|
|
|
|
|
6 months? Sometimes last week is more like it!
I have to say that I do not ever comment code to say what it does. It should be obvious, as the saying goes 'it does what it says on the tin!'. If it is not obvious then either the method is to long, or the method is badly named.
Hoever, I always comment what I was thinking at the time. At least then I know why I wrote this rubbish, and it is usually only rubbish if the reasoning/understanding of the problem was wrong, or the problem changes.
|
|
|
|
|
Dalek Dave wrote: Also, why is it possible to select "I don't Comment" and any other comment selection? Mutual Exclusivity!
I won't comment on that.
|
|
|
|
|
But, in fact, you still can.
Ninja (the Nerd)
Confused? You will be...
|
|
|
|
|
I was in middle of code handover at client premises, and the IT personnel was like: "I cannot see any comments in your code  "
Then we did.
Noman Muhammad Aftab,
Software Mechanic
|
|
|
|
|
It's going to be interesting to see the result...
modified on Monday, July 19, 2010 4:43 AM
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
