|
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...
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
|
|
|
|
|
Comments should be kept up to date, and can be very useful.
Anyone whose done maintanance in old code knows that accurate descriptions of why things were done, or changed can be lifesavers. What was this person thinking? Oh, because of that bug, this patch was done, with this complication. Now I see why I can't change what it does, someone depends on this wierd behavior. My rewriting would cause a bug report.
Worked with a consultant who said code comments itself. Yeah sure, but it takes me far longer to figure out, especially your "ellegant" code, without some declaration of what its supposed to be doing. Or why some change several years ago was made by someone long gone from the company.
|
|
|
|
|
As long as the comments are relevant for the reader and help in understanding the structure, yes. I wouldn't go as far as making it required, because that's asking for gems like these;
int i = 0; Printed documentation tends to get lost, even Word-documents and readme.txt files tend to get separated from their archives. However, if you include a 20-page document called "maintenance.cs" and put it completely in /* comment-marks */ , it tends to stay with the source.
I are Troll
|
|
|
|
|
Yes, the example isn't useful.
But, how about a comment on how i is used, since its name isn't descriptive? At least a block comment about what's happening, even a loop with ++i isn't obvious if you don't see what's being counted...
|
|
|
|
|
Although I find myself incline to add comments to the code I always find the code harder to read later, it just makes the code harder to read, it loses style and becomes noise. However, I always add comments when fixing code to have a reference to the ticket and a brief description of the problem.
|
|
|
|
|
I absolutely agree with you.
CDMTJX wrote: said code comments itself
Yes, I know this "excuse" but it is a "bad" excuse Also others says: Unit-Tests "comment" the code. This is participial correct "good" comments are still required.
|
|
|
|
|
people say "I cannot remember what my code does without help of comment", unless they were programming using a language they were not good at to begin with. Or they suffered some serious head injury or disease, etc. It may take a little longer for me to understand/remember what my code does, there is no single case that I couldn't figure it out eventually.
|
|
|
|
|
"figuring it out eventually" and "not remembering" are two different things! If you have to "figure it out eventually", then you forgot it. Where time is money, it's faster to read a comment than it is to try and figure it out. Plus, there is no way that I can remember the details of code that I did 25 years ago. (that's when alot of current programmers were born!)
|
|
|
|
|
But I did not remember reading a comment has ever helped me. If there are more than one programmers working on the code, then the comments are very likely to be out-dated and cannot be trusted.
Member 3253258 wrote: there is no way that I can remember the details of code that I did 25 years ago
Are you saying you are still maintaining code from 25 years ago? With no exageration?
|
|
|
|
|
Xiangyang Liu 刘向阳 wrote: But I did not remember reading a comment has ever helped me. If there are more than one programmers working on the code, then the comments are very likely to be out-dated and cannot be trusted.
Have you done much work in assembly language? Coming back to even a somewhat trivial piece of code a week later is much easier if you have code explaining what's going on and why.
It's less necessary with more expressive languages, but now and again it's useful for maintenance. It's also very important when using frameworks and libraries written by others of course!
|
|
|
|
|
destynova wrote: Have you done much work in assembly language?
None. I guess my argument does not apply to people using assembly languages, maybe unix shell script and perl as well. Just wondering, how much comments do you have to write for assembly code? Maybe 10k of comments for every 1k of code?
destynova wrote: if you have code explaining what's going on and why.
You have to write code to explain what you assembly code does? Sorry, can't help it, I know you meant comment instead of code.
|
|
|
|