|
/*
Write a good documentation, with all features like procedure header, function description,... . See, you don't need any comment in your code. And if the other don't understand your code-he's just not good enough for working with your code.
*/
Comments are only useful in one language-vbasic. Basiccode have to look like this.
Sub Form_Load()
'Dim a as Variant
'Dim b as Variant
'Init a, b
End Sub
//VB-looks much better with comments.
//Excuse my bad English 
|
|
|
|
|
What a bunch of crap, Colin!
Most engineering has some type of blueprint. All the programmer might get is the bit of comments left by the fella before him.
Not every programmer is an expert in the language they are coding in. whether it's the one creating the mess or maintaining it. Coments are the only way to help give the next guy a clue as to what you were aiming at.
"Manifest plainness, embrace simplicity,
reduce selfishness, have few desires."
-- Lao Tzu BW
|
|
|
|
|
brianwelsch wrote:
Most engineering has some type of blueprint.
Yes, but the blueprints are for the designer or the project creation team to develop. The programmer is working to there specification, he/she should not be developing the project.
Have you ever seen a Maintenance programmer ask to look at the original user requirements or specification?
brianwelsch wrote:
Coments are the only way to help give the next guy a clue as to what you were aiming at.
What about logic and ability, and dataflow analysis and deskchecking, have we left those skills in the dask ages ?
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch ![Green Alien | [Alien]](https://codeproject.global.ssl.fastly.net/script/Forums/Images/alien.gif) "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Colin Davies wrote:
What about logic and ability, and dataflow analysis and deskchecking, have we left those skills in the dask ages ?
In the past 18 mths. I've coded a c++ project from scratch with very few specs. It was being redesigned halfway through, because of some new ideas from the powers that be. Also, it was my first C++ project beyond classroom code. So the code I added through helped me quickly figure out what I was thinking and what was going on.
Currently, I'm dabbling in assembly, another new language for me, which isn't even standard, but littered with macro calls. I'm grateful for the couple of comments which are given.
I do alot of plotting out by hand, following data through by hand, etc, but the clocks ticking.
"Manifest plainness, embrace simplicity,
reduce selfishness, have few desires."
-- Lao Tzu BW
|
|
|
|
|
(ducks grenades being lobbed by Davies)
Software Zen: delete this;
|
|
|
|
|
Gary Wheeler wrote:
(ducks grenades being lobbed by Davies)
Nah, I wouldn't do that.
I didn't really expect anyone to agree with me though.
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
When I'm in a 'let natural selection take its course' sort of mood with regards to my co-workers, I agree with you. Fortunately for them, that only happens a couple times a week  .
If you take a look at my post[^] below, you'll see how I choose what to comment. If it is more consise to say something in code, I'll do so. If it's more straightforward to say it in a comment, and let the const's fall where they may, I'll do that.
Software Zen: delete this;
|
|
|
|
|
Maybe I have been turned away from comments and understandability in recent years by the ammount of over commented understandable code that is poorly written.
I think if some programmers put as much effort into programming well as what they do to commenting then we would be all a lot better off.
Yes, there are places for comments, in the start of files, and in headers for access, etc.
But commenting every line of code like:
iLoop++;
has become far to prevalent.
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Indeed. Once I started commenting only what I needed to, my productivity went up. It's embarrassing how much time I used to spend, documenting every little thing:
int i;
Nowadays, I use comments to explain rationale, insert references to background material, and describe version history.
Software Zen: delete this;
|
|
|
|
|
//quote from Colin's post. Used as reference to original post
Colin Davies wrote:
But commenting every line of code like:
// response to Colin's post
I agree with you on that, Colin. A certain level of understanding should be expected.
//signature
"Manifest plainness, embrace simplicity,
reduce selfishness, have few desires."
-- Lao Tzu BW
//end signature
//end post
|
|
|
|
|
///
/// /*brianwelsch wrote:
///I agree with you on that, Colin */
///
/// /* Thanks Brian */
///
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Worked on complicated highly optimised number crunching code lately? Worked on code that is nessy because it had to do a long-winded workaround to solve a non-intuitive and non-trivial OS or library bug?
And then had to share this code with others?
I thought not.
cheers,
Chris Maunder
|
|
|
|
|
Chris Maunder wrote:
And then had to share this code with others?
You are correct.
Having to share code is the real problem in this and many other sitautations.
What surity do you have that who reads or examines the code will be understand it anyway.
Thus the developer will need to work to the highest common factor realistically possible, and the principles of peer review go out the window.
Having to educate your co-workers is hardly ever in any job description to my knowledge.
Regardz
Colin J Davies
* WARNING *
This could be addictive
The minion's version of "Catch "
It's a real shame that people as stupid as you can work out how to use a computer. said by Christian Graus in the Soapbox
|
|
|
|
|
Whitespace is your friend, use it wisely... I hate downloading code that looks like this:
#include <iostream.h>
void main()
{
cout<<"Hello world!"<
|
|
|
|
|
That last post was me! i wasn't logged in 
~DaN
|
|
|
|
|
That is nothing compared to some of the garbage code that has been posted here
This is an example of too many enters rather than spaces:
void function
(
int param1,
int param2
)
{
}
If only I could remember what article it was... it was fairly recent
|
|
|
|
|
I use the tab key religiously, and I line nearly everything up. The result looks something like this:
labels = new Label[9,12] ;
labels[0,0] = new Label() ;
labels[0,0].Image = new Bitmap( "tile.bmp" ) ;
I didn't write this but I love how the {} line up:
protected override void Dispose( bool disposing )
{
if( disposing )
{
if ( components != null )
{
components.Dispose();
}
}
base.Dispose( disposing );
}
|
|
|
|
|
Hmmm. I tend to use K&R style braces:
if (...) {
}
for (..) {
}
but I do tend to include a fair number of blank lines in my code. I've found it's easier for me to read, with blank lines breaking things up every so often. One thing I've always disliked, however, is the extra spaces people put before and after the parentheses in a function call:
SomeFunction ( argument1, argument2 );
Software Zen: delete this;
|
|
|
|
|
|
Gary R. Wheeler wrote:
if (...) { //... } for (..) { //... }
Agreed.
Gary R. Wheeler wrote:
SomeFunction ( argument1, argument2 );
Definitely agreed!
The kindest thing you can do for a stupid person, and for the gene pool, is to let him expire of his own dumb choices.
[Roger Wright on stupid people]
|
|
|
|
|
If you make easily understood source code then the programmer and the viewer will understand it better and should just about speak for itself.
But then again if you comment ALOT then you probably won't find alot of things out and you are spending a huge amount of commenting which when compiling the program will be useless and if you spent more time making and improving better code, then your program, (I think), would be alot better.;)
Don't get me wrong, you should comment it but as little as possible so you or someone else looking at it should understand what it's supposed to do.;P
<marquee>Universal Project... Soon to be a .net
|
|
|
|
|
See my post below - I partly disagree. Well written code can tell you what. But you need comments, or knowledge of what your program does, to decipher why.
Comments are invaluable when dealing with an API from a large, well-known software corporation that occasoinally has bugs or undocumented "features" that have non-obvious workarounds.
"When a man sits with a pretty girl for an hour, it seems like a minute. But let him sit on a hot stove for a minute and it's longer than any hour. That's relativity." - Albert Einstein
|
|
|
|
|
If you recall I didn't say that comments were totally bad if you had read all of it. 
<marquee>Universal Project... Soon to be a .net
|
|
|
|
|
.. but you get none !
:evil:
i'm only pointer to myself
|
|
|
|
|
More often than not, though, you're right...  :puke:
"When a man sits with a pretty girl for an hour, it seems like a minute. But let him sit on a hot stove for a minute and it's longer than any hour. That's relativity." - Albert Einstein
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
