|
The biggest problem with commenting is keeping them in sync with the code. The majority of comments I read in others' code refers to old code that has since changed. Sometimes the comments refer to code that isn't even there anymore. When they're out of date comments do more harm than good.
I agree with another poster here that, ideally, comments shouldn't be necessary. Unfortunately so long as what we're writing is more 'code' than 'requirements' we'll need them.
-jmw
|
|
|
|
|
We need at least the same level of comments as there are in say the MSDN Library, i.e., for all public classes and methods, etc. But inline code comments do indeed run the risk of being outdated. I often use the "comments to code" strategy, i.e., any inline summary comments are used as indicators of where to refactor the code into a private method named after the comment. Then I dispense with the comments.
|
|
|
|
|
But I don't know how many programmers do comments on there code. sometime I just forget to add comments
|
|
|
|
|
a necessary evil. I do find that obscure methods are easier to decipher at a glance with some kind of lead in, and do appreciate that. In .Net, the xml method comments also add a kind of symmetry to the layout which I like. Beats sifting through thousands of lines of IOS script spagetti in my day job, where I wish comments were more the norm..
|
|
|
|
|
I agree. Looking through other peoples code with no comments is a lot more time consuming when there are no comments. And in addition to no comments, where people dump almost everything in one file lol 
|
|
|
|
|
I believe good and consistent formatting of code, as well as properly named variables, make the code readable enough without the need for lots of comments. Only comment those pieces of code where business logic needs to be spelled out or the purpose of the code is not clear. Too many comments tend to make the code unreadable.
|
|
|
|
|
Depending on the language comments may not be required. This is why I like VB alot. It is very readable and it can do 95% of what any other .NET language can do.
With a language like C++ I would make commnts required. Just in case a Jr. Programmer has to maintain something.
|
|
|
|
|
There are a few things about a code snippet:
- what it does
- why it does what it does
- what can go wrong
- how to reuse it
Readable code helps with what it does.
why might get some suggestive nudges from the what, encapsulation and error conditions might be partially covered in coding standards, but generally these still require comments.
|
|
|
|
|
It depends also on your adherence to design patterns - which can often make the why quite obvious. Sometimes I leave the why for version control comments, particularly if it's a bug correction that still leaves readable code.
|
|
|
|
|
Does the majority of your code consist of the implementation of design patterns? I'm not sure if I should envy or belittle that 
Maybe if you stamp out "database - business rules - input forms and reports" again and again. My job consists of walking rather awkward data structures, gluing COM stuff togeter and non-standard signal processing. Any why comment is appreciated there.
Some of the why can be put into good naming conventions etc. However, with the tendencies of engineers who think p, v, P, t1 and r_t are quite obvious names and the naming conventions and C trickery of Numerical Recipes was good 20 years ago so why should it be bad today, any "why" is appreciated. (Actually, event the "what"'s make me happy.)
As checkin comments I use either a feature description or simply a bug tracker case number.
|
|
|
|
|
It's difficult to judge the "majority", but in general, in my last big c# project, I had to explain the why only in two cases where we had to do workarounds and in one wizard-like scenario which involved a lot the session - the rest was basic MVC plus ORM. There were also a lot of specifications and bug tracking for the more high-level "whys".
In the SQL part of my job, though (we are doing a lot of bulk processing in the company), I do have to write the "why", exactly because there aren't any serious design patterns there, so I understand what you're talking about.
And I agree a lot about naming conventions. In some cases, where I know that I will not have to call a Stored Procedure in a lot of places, but I want to know exactly what it does, I might name it "CalculateProductStatusAfterPuttingOnLine" - to know exactly when I should call it and what's its purpose - in addition to documenting the whole process if it's complicated enough.
|
|
|
|
|
I absolutely agree. My C# code has almost no comments, my SQL stored procedures have PRINT statements (which help as comments) at about every two queries (we have some very complex monsters, reaching 1800 lines in the worst case - refactored!)
|
|
|
|
|
I had the unpleasant task of going through a stored procedure with about 3800 lines. And of course there were almost no comments for what the different sections were doing. Some comments here and there would've saved me a lot of time. 
|
|
|
|
|
Real Programmers don't comment their code:
if it was hard to write, it should be hard to understand 
Well, that joke is from somewhere else and came from the sixties.
When I write something strange, but beautiful, I comment it. Not only for my followers, also for me^^
|
|
|
|
|
Kevin Drzycimski wrote: Real Programmers don't comment their code:
if it was hard to write, it should be hard to understand
That sounds like something someone I work with would say haha
|
|
|
|
|
How many Murphy's laws do they have about this topic?
- Anything that can possibly go wrong - does,
- If a program is useful, it will have to be changed
- If a program is useless, it will have to be documented.
- ...
If you are trusting what somebody else said the program does, instead of relying on facts and your own recent experience - you are asking for trouble. Reminds me of movie 'Underseige 2' - assumption is a mother of all screwups.
I have been doing programming for more then 20 years in pretty much anything - assembler, c/c++, java, vb, c# - you name it. I worked with probably over 200 developers and more then million lines of code (about quarter - mine) and by now trained myself just to skip over documentation. The only thing I rely on is debugger and search tools. Unless you intimately familiar with the module you are working on - you have no business of changing it. Going solely by the documentation done by the person you never met - insanity.
|
|
|
|
|
Like you, after (40+) years as a designer/developer, I've learned the hard way that I can't trust any documentation to actually match the production code.
BUT:
1) When working on a production problem (ie: at 3 am from home or a remote site), I may not have access to my toolsets, read (much less write) access to a production database, or any access to a debug database or system logs, trace files, etc., that are behind a firewall. You also seem to be assuming a robust debug environment exists, has up-to-date data, and/or is not in the format of the next release, etc.
2) I may have designed the application but not developed it; thus, I may not have access to the source code library, etc. I could be looking at only a copy or snippit of code.
3) I may even be in a consulting only role at the moment. It could be I don't have sufficent overall system understanding and/or time to set-up test scenarios/data for debugging a little function within a large complex process, etc.
Simply put: System/code search/debugging/tracing/etc tools may not be an option ... at all or at the moment.
Thus, I look for some documentation to give me a baseline understanding of the code and the mindset of the coder faster (ie: what was this guy thinking when he wrote this junky code ... whoops, I wrote it years ago).
Do I trust (any) documentation? NO!
Do I find it helpful? Yes (generally).
GoodTime Charlie, VA
|
|
|
|
|
Nice to hear that some people stay in our business long enough to earn gray hear. Any way back to the topic. Every now and then I also get put in position of troubleshooting somebody else code in production environment without debugger, under time stress, with everyone breathing down your neck or in the middle of the night/weekend. There were cases back in my java days, when on top of that there was no source - just JAD output. But you know what, I never found other people comments helpful and relevant at the same time. It seems to always be either trivial (something like /* declaring integer loop index */) or misleading.
It is however something customary in the business - we are conditioned to do it. Plus it gives you an extra excuse/bitching point - look what I have to deal with - bad/no comments.
|
|
|
|
|
Comment make code readable....
comment make code simpler to understand...
comment helps developer to understand the code done by earilier developer, helps to understand his assumptions
GIVE COMMENT TO MAKE CODE LIVE...![Rose | [Rose]](https://codeproject.global.ssl.fastly.net/script/Forums/Images/rose.gif)
Rating always..... WELCOME
Be a good listener...Because Opprtunity knoughts softly...N-Joy
|
|
|
|
|
I found that after several revisions, comments become less readable because of the comments on comments.
TOMZ_KV
|
|
|
|
|
Tomz_KV wrote: comments become less readable because of the comments on comments
You are not talking about Mike (see thread below), are you? 
|
|
|
|
|
No. That was a coincidence.
TOMZ_KV
|
|
|
|
|
Although you may eventually figure out what or why you or someone else did what they did it is a lot easier and faster when comments are added.
To me it's like a highway without any signs or markers, you know you need to go in a certain direction, you may run into dead ends or other obstacles but you will eventually get there but if there are signs/markers the way is much clearer and faster.
My two cents,
Mike
|
|
|
|
|
Obviously you are not living in Germany where those "helpful" signs are so cluttered all over the place that you are too confused to even move.
|
|
|
|
|
In very congested cities we are also over whelmed with signs that seem to point to every where but nowhere.
Anything to excess is not good...or as my ex-wife used to say, "At least he's trying, real freaking trying"!
Mike
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
