|
Hello, the CPians around the world.;)
I strongly doubt that easily understandable code exists?
(I mean that everybody understans every codes at the huge projects.)
If so, the programmer like C++ will not get the high salary. 
As long as I am concerned, I only add the comment for the difficult understanding codes like that I spend much time to figure out the bug or BOOL value to prevent the error process.
That is, if anybody easily understand my codes, I never add my comments.
But, I guess that the other ppl may have some pitfalls like mine, I try to add
my comments.
-Masaaki Onishi (eCoolSoft)-
ASP.NET Web and Windows
Application Development by C# and MFC.
eCoolWebPanelBar(BETA) is availabe now.
http://www.ecoolsoft.net/homepages.aspx
|
|
|
|
|
The problem with the "if code is readable, then no comments are needed" argument is that it ignores the complexities of large projects. As another person said, just because you know what is happening doesn't mean you understand why it is happening.
Recently I fixed a bug in our internal tools here at BioWare. The problem was that our model viewer program wasn't working with the lighting system for the advanced model rendering paths. Only one line of code was required to fix the problem.
roomlights = renderlights;
Looking at the code, we know what the code is doing. The code is making a copy of all the rendering lights and placing them in the room lights list. But the question is why are we doing this and why is it so important that it happens? If someone needed to modify this routine, what dependency must he be aware of in order not to break functionality?
Tim Smith
I'm going to patent thought. I have yet to see any prior art.
|
|
|
|
|
Tim Smith wrote:
just because you know what is happening doesn't mean you understand why it is happening.
Good point. However, comments only help you to understand "why" in simple projects as does good code.
Too much infoirmation is the same as (if not worse than) no information at all. For example, we get all kinds of documents and statements from our 401k and other investment plans, those things just fill our recycle bins, they seldom make us understand more about the stocks in our portfolio.
A lot of detailed comments can easily mislead or confuse the developers. Also, keeping all the comments up-to-date is not a simple job.
|
|
|
|
|
Like this one:
<br />
i++;
|
|
|
|
|
Yes! That's the kind of comment which allows your boss to stop make comments about you RSN. 
BTW, you forgot the javadoc-like comment.
--
Frivolous Theorem of Arithmetic: Almost all natural numbers are very, very, very large.
|
|
|
|
|
I have found that it is absolutely invaluable to have a function header at the top of each function that supplies the following basic concepts:
what's the purpose of the function?
what are the individual expected inputs (if any)?
what does the return value mean (if any)?
what assumptions/constraints apply to the input (if any)?
This to me is more important than legible code, and here's why: If you're working on a project that lasts longer than a month then inevitably, you will come to a point where you need an object to do something. You have the concept of what you want it to do in your mind, but you're not sure if it already does it or not. At this point, the last thing I want to do is go back and read code to try to figure out how closely a given function matches my need. I found that being able to browse through function headers increased my efficiency dramatically. Most of the time, I have a vague idea that I coded something like that 6 months ago, but I don't remember what it was called or how exactly I should call it. Browsing these function headers allowed me to very quickly find a function (or a group of functions) that matches the exact description of what I need and will do the job. At this point, I no longer care what the code looks like (assuming that it's working). I just want to be able to call a function that does what I need.
Now, I personally prefer nice, neat, "self-documenting" code within these functions, but suppose it isn't. This isn't really a problem to me, as long as the function does exactly what it says it will do. If it doesn't, and the code is ugly, then I still prefer the function header, because the header gives me an exact picture of what the code should be doing. This way I can fix the ugly, non-working code, without regard to how it's being called and from where. Just make it work as the description promises.
I know that this system has its flaws, but I just headed up building a large application and I was extremely strict on myself and my fellow coders with regards to the use of function headers, and everyone on the project was in agreement that it paid off big-time in the long run, even those who were originally against the idea.
Chris Ellis
|
|
|
|
|
Easily understandable code probably means nicely structured code and that will probably result in better compiler optimizations (not always of course, some unreadable code tricks produce very optimized code, but that is for advanced programming . So people should always try for nice, clean code.
|
|
|
|
|
<br />
if(employee.Age() > 58)<br />
{<br />
if(!employee.IsFired())<br />
employee.ShouldFire(TRUE);<br />
}<br />
In my opinion, above piece of code is "Easily understandable code" and "nice, clean code."; but can you understand it? If you are asked to fix it, can you "fix" it without any comment?![Rose | [Rose]](https://codeproject.freetls.fastly.net/script/Forums/Images/rose.gif)
IMHO, comment should at least explain why/reason/business-logic.
|
|
|
|
|
I disagree - the business rule is plain for any reader - fire anybody over 58... I wish half the code I worked with were this easy to follow.
If I'm asked to 'fix' it, I assume someone will tell me what the problem is - "We want to start firing people at 45" or "It's not legal to do this." Given a statement of the problem, and the code above, it's pretty easy to fix.
Even in this example:
<br />
if (employee.Age() > 58 &&<br />
employee.getSuperSecretValue() < 7 &&<br />
employee.getToastPreferences() != prefWellDone)<br />
What could a comment add?
Do these reasons have a bearing on the actual business rule, which is apparent from the code itself?
Personally, my pet peeve is this:
<br />
app.initialize();<br />
file.open();<br />
<br />
file.print();<br />
Those fine example of commentary are by far the most common I see. Completely useless... but people seem to think that they serve a purpose.
- Renault
|
|
|
|
|
>>What could a comment add?
//HR Group#: 356-789-658-08062003
//Damn Fxxx, Gonna create a back door in case I still work here when I am ...
if(employee.Age() > 58)
{
if(!employee.IsFired())
employee.ShouldFire(TRUE);
}
|
|
|
|
|
Anonymous wrote:
if(employee.Age() > 58)
{
if(!employee.IsFired())
employee.ShouldFire(TRUE);
}
If you use studio you can jump between functions/methods by pressing F12 or if you use Viasual Assist Alt+G...
This is much better. BTW if all functions written in the same good manner then fixing will take 10-15 minutes. Good time for any kind of fix.
Good Luck
Alex Kucherenko
|
|
|
|
|
Easily understandable would be preferrable as you directly assimilate it instead of reading about it. Nevertheless, straght roads and very clear code are seldomly possible to create. Speed optimization kills clear code, for example. In these cases, good comments are essential.
The developer should discern about which portions of code should be well commented and explained and which portions are self explanatory.
Regards.
G. Raven
|
|
|
|
|
G. Raven wrote:
The developer should discern about which portions of code should be well commented and explained and which portions are self explanatory.
An excellent point. There are times (unless you're a government worker in laboratory conditions with endless budgets) when straight forward code is impossible without retooling a major portion. Yes, in reality, eventually, somewhere, you're gonna write yourself into a corner...
So when that happens, comment well.
Paul
|
|
|
|
|
Personally, I don't like comments interlaced in the code. It reduces the readability of both, and the aesthetics of well-formatted code (which is valuable information in itself). So, I put my comments out past column 100 usually (well, obviously, comments outside of methods and classes aren't hanging out there in space--just the ones associated with a line of code).
For me at least, it's very visually appealing. So, I really can't understand why a lot of code guidelines say "nothing past column 80". WTF? It's not like we're programming on teletypes!
But then again, my commenting style really makes it a PITA to reformat code for a CP article!
Marc
Latest AAL Article
My blog
Join my forum!
|
|
|
|
|
Marc Clifton wrote:
So, I really can't understand why a lot of code guidelines say "nothing past column 80".
It makes it easier to read when you print out the code. I one of those who tries to stick with this convention... a task not made easy but the my tendency to use descriptive variables names, not mentioning all the System.Somthing.Microsoft.Pain.the.Ass namespaces.
Michael
'War is at best barbarism...Its glory is all moonshine. It is only those who have neither fired a shot nor heard the shrieks and groans of the wounded who cry aloud for blood, more vengeance, more desolation. War is hell.' - General William Sherman, 1879
|
|
|
|
|
Michael P Butler wrote:
It makes it easier to read when you print out the code.
I think it's been about 10 years since I last printed out code.
Michael P Butler wrote:
a task not made easy but the my tendency to use descriptive variables names, not mentioning all the System.Somthing.Microsoft.Pain.the.Ass namespaces.
Amen, bro'! I wish namespaces could be aliased.
Marc
Latest AAL Article
My blog
Join my forum!
|
|
|
|
|
Marc Clifton wrote:
I think it's been about 10 years since I last printed out code.
I'm a bit of a dinosaur when it comes to programming. I still like having a printout of the code for when I'm debugging or reworking a section of code. I never have liked reading code on a screen... to easy to miss something.
Michael
'War is at best barbarism...Its glory is all moonshine. It is only those who have neither fired a shot nor heard the shrieks and groans of the wounded who cry aloud for blood, more vengeance, more desolation. War is hell.' - General William Sherman, 1879
|
|
|
|
|
Marc Clifton wrote:
I think it's been about 10 years since I last printed out code
The only time I print code anymore is when I'm debugging a large piece that takes up more than 3-4 screens. At that, I only print the fragment I'm concerned with. I'll print single page snippets of things occasionally to refer to, if I don't want to clutter the screen with an open window just for reference.
Software Zen: delete this;
|
|
|
|
|
They actually can...
using System.Text;
Encoding ascii = Encoding.ASCII;
|
|
|
|
|
They can my friend!
using cn = System.Console;
C# is good! 
|
|
|
|
|
Marc Clifton wrote:
I think it's been about 10 years since I last printed out code.
Sometimes you have no choice. In my project group, when it comes time for a peer review, we print the code and pass out packets.
Oh, yeah, and Visual Studio tends to eat up half your screen space w/ all of its docked windows anyway - it's amazing, my screen keeps getting bigger, but the number of columns of text on screen just stays the same!
|
|
|
|
|
Stephen Quattlebaum wrote:
my screen keeps getting bigger, but the number of columns of text on screen just stays the same!
That's exactly what I've been saying for the last 5 years. But I've gotten even. I've an extra monitor now. Muhahahahah!
--
Frivolous Theorem of Arithmetic: Almost all natural numbers are very, very, very large.
|
|
|
|
|
Michael P Butler wrote:
'War is at best barbarism...Its glory is all moonshine. It is only those who have neither fired a shot nor heard the shrieks and groans of the wounded who cry aloud for blood, more vengeance, more desolation. War is hell.' - General William Sherman, 1879
'War' is what gave you the right to quote General William Sherman!
|
|
|
|
|
Marc Clifton wrote:
nothing past column 80
Are you using VS.NET?
cheers,
Chris Maunder
|
|
|
|
|
Chris Maunder wrote:
Are you using VS.NET?
Yes. On a 17" wide screen laptop with 8 point font. The rightmost column is #200. And yes, I know about the margin guide feature, which is turned off, as are horizontal and vertical scroll bars and that stupid selection margin. (if you can't navigate with a keyboard, what is the point of being a programmer, eh?) I want to see code. Period. 
I'm curious why you ask, though.
Marc
Latest AAL Article
My blog
Join my forum!
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
