code comments
-
I have found that "50 Specific Ways to Improve Your C#" is really good, and one of the things that the author Bill Wagner points out is that your code should be self explanatory, and not require much in comments. Good variable names helps a lot.
:thumbsup: And good function names/class names. And a alear breakdown of code into bitesized pieces. Aptly named.
#SupportHeForShe Government can give you nothing but what it takes from somebody else. A government big enough to give you everything you want is big enough to take everything you've got, including your freedom.-Ezra Taft Benson You must accept 1 of 2 basic premises: Either we are alone in the universe or we are not alone. Either way, the implications are staggering!-Wernher von Braun
-
I hate code comments that say what the code is doing but not why.
/* check for null */
if (someObj != null) {...}Really? Argh!
#SupportHeForShe Government can give you nothing but what it takes from somebody else. A government big enough to give you everything you want is big enough to take everything you've got, including your freedom.-Ezra Taft Benson You must accept 1 of 2 basic premises: Either we are alone in the universe or we are not alone. Either way, the implications are staggering!-Wernher von Braun
This seems like suspiciously good timing: Documentation just before vacation | CommitStrip[^] :D
"These people looked deep within my soul and assigned me a number based on the order in which I joined." - Homer
-
The new approach (v6.0) is the null conditional operator, so you don't need to check for null.
someObj?.DoStuff();
Regards, Nish
Website: www.voidnish.com Blog: voidnish.wordpress.com
I think that's what JSOP was referring to as the "bullsh|t operator".
#SupportHeForShe Government can give you nothing but what it takes from somebody else. A government big enough to give you everything you want is big enough to take everything you've got, including your freedom.-Ezra Taft Benson You must accept 1 of 2 basic premises: Either we are alone in the universe or we are not alone. Either way, the implications are staggering!-Wernher von Braun
-
This seems like suspiciously good timing: Documentation just before vacation | CommitStrip[^] :D
"These people looked deep within my soul and assigned me a number based on the order in which I joined." - Homer
Damn you beat me to it by 15 min :)
Tom
-
I think that's what JSOP was referring to as the "bullsh|t operator".
#SupportHeForShe Government can give you nothing but what it takes from somebody else. A government big enough to give you everything you want is big enough to take everything you've got, including your freedom.-Ezra Taft Benson You must accept 1 of 2 basic premises: Either we are alone in the universe or we are not alone. Either way, the implications are staggering!-Wernher von Braun
-
I am one of the other poor b*st*rd now. The original developers think their code is so beautiful and wonderful that no comment is needed to explain. They think I should ask if I do not understand. It will take longer than my lifetime to finish project this way.
My sympathies. Been there, hated it. Look at the bright side, though: if the job were too easy, you'd get bored. Mind you, the jury's still out on which of bored and tearing-your-hair-out-in-frustration is worse.
I wanna be a eunuchs developer! Pass me a bread knife!
-
:thumbsup: And good function names/class names. And a alear breakdown of code into bitesized pieces. Aptly named.
#SupportHeForShe Government can give you nothing but what it takes from somebody else. A government big enough to give you everything you want is big enough to take everything you've got, including your freedom.-Ezra Taft Benson You must accept 1 of 2 basic premises: Either we are alone in the universe or we are not alone. Either way, the implications are staggering!-Wernher von Braun
Yes. That and using good encapsulation. On one project they passed all 3-d point vectors as separate arguments. They also had 1000+ line methods.
-
I hate code comments that say what the code is doing but not why.
/* check for null */
if (someObj != null) {...}Really? Argh!
#SupportHeForShe Government can give you nothing but what it takes from somebody else. A government big enough to give you everything you want is big enough to take everything you've got, including your freedom.-Ezra Taft Benson You must accept 1 of 2 basic premises: Either we are alone in the universe or we are not alone. Either way, the implications are staggering!-Wernher von Braun
-
The new approach (v6.0) is the null conditional operator, so you don't need to check for null.
someObj?.DoStuff();
Regards, Nish
Website: www.voidnish.com Blog: voidnish.wordpress.com
Often, in cases like that, you could very well add a comment indicating why the ojbect reference would be null (or non-null). Not always, but often. When studying code written by others, one of the questions I frequently as myself is of the kind "OK, so I understand that you can't Do Stuff on a null object, but in which cases is the object null?? A short end-of-line comment such as 'null if child hasn't been named yet' or 'null if cleanup actions are already performed' can be worth their weight in gold.
-
I hate code comments that say what the code is doing but not why.
/* check for null */
if (someObj != null) {...}Really? Argh!
#SupportHeForShe Government can give you nothing but what it takes from somebody else. A government big enough to give you everything you want is big enough to take everything you've got, including your freedom.-Ezra Taft Benson You must accept 1 of 2 basic premises: Either we are alone in the universe or we are not alone. Either way, the implications are staggering!-Wernher von Braun
Back in the Dark Ages, I worked with DEC's RT-11 operating system. It was written in PDP-11 assembler. I had the opportunity to look at the commented source code, and I remember the following line:
NOP # We don't know why it's here, but it doesn't work without it.In a proprietary OS. From the manufacturer of the CPU. Sometimes commentary will reveal far more than you ever wanted to know.
Freedom? That is a worship word. -- Cloud William The only thing a free man can be forced to do is die.
-
:thumbsup: And good function names/class names. And a alear breakdown of code into bitesized pieces. Aptly named.
#SupportHeForShe Government can give you nothing but what it takes from somebody else. A government big enough to give you everything you want is big enough to take everything you've got, including your freedom.-Ezra Taft Benson You must accept 1 of 2 basic premises: Either we are alone in the universe or we are not alone. Either way, the implications are staggering!-Wernher von Braun
Reminding me of a fellow student (long, long time ago!) writing his programs using variable names like I001, I002,... F001, F002 (for floating point values). Before handing in the exercise he would to a global replacement of, say, I001 with 'NumberOfEggsPerBox' or someting like that. Writing those long names while developing the program would require too much typing, he argued. Also it served as a limited 'copy protection'. It was too easy in those days to access the work of fellow students, to use as a basis for your own exercise solution. Martin never had his half-finished work 'stolen' - understanding it (before the last-minute variable name replacement) required as much effort as developing your own solution.
-
Back in the Dark Ages, I worked with DEC's RT-11 operating system. It was written in PDP-11 assembler. I had the opportunity to look at the commented source code, and I remember the following line:
NOP # We don't know why it's here, but it doesn't work without it.In a proprietary OS. From the manufacturer of the CPU. Sometimes commentary will reveal far more than you ever wanted to know.
Freedom? That is a worship word. -- Cloud William The only thing a free man can be forced to do is die.
Like http://geek-and-poke.com/geekandpoke/2013/7/28/tdd[^] While we are talking about assemblers: Long time ago (around the RT-11 times), I looked into the source code of the assembler, of course written in assembler. Yes, the code was commented. Only that each and every comment was like 'Smart trick here!' and 'This is messy but it works' or 'Faster than [...]'. And the module heading (that is if you consider an assembler source file a 'module' :)), there was a comment referring all questions, problems and bugs to R.S, which at the time when I read it, was the CEO of a 3000 man company...
-
Yes. That and using good encapsulation. On one project they passed all 3-d point vectors as separate arguments. They also had 1000+ line methods.
The company I worked for, many years ago, had to deliver to a valued customer a pre-relase of the new and completely rewritten Fortran compiler: The old compiler could only handle 99 arguments to a function, and this customer had crossed that limit. The new compiler handled 127 arguments, but extending it to 255 arguments was a simple matter. Another company I worked for had to update their linker program: The table of symbols defined and exported by a module could hold only 32767 elements. The customer crossed that limit. By changing the declaration of an index variable from signed to unsigned 16-bit, the linker could handle 65535 exported symbols. I believe the customer never crossed that limit - even though the software had a struct declaration of approx 8300 lines :-D .
-
What's more disturbing is that C# *still* doesn't allow this:
if (!someObj) {...}
which would preclude them from having to come up with the bullsh|t "?" operator.
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
When you pry the gun from my cold dead hands, be careful - the barrel will be very hot. - JSOP, 2013On the other hand, I most definitely hate the (much too common) C construct 'while (1) {...}' In embedded code, you frequently have infinite loops, and in some software I was handling, I declared a const bool WW3 = false, and changed the loop to 'while (!WW3) {...}'. That really upset one of the other programmers, who edited it back to 'while (1)' with some really nasty comments in the SVN log. I tried to adopt the CHILL idea: In CHILL, 'EVER' is a reserved word, and the 'official' way of writing an infinite loop is 'DO FOR EVER [...]'. So I set up a '#define ever ;;' so that I could write (in C) 'for (ever) {...}'. But even that was too much for this other programmer; he insisted that 'while (1)' is The Professional Way of writing an infinite loop. I let him have his will.
-
I was always taught that code comments are to describe a process your code is doing, if it is complex and not easily understood from the existing code base - otherwise, don't comment. It has served me well, all these years, so I stick with it...very minimal commenting in my code.
Bah!! find something to complain about for Betsy's sake! If some lonely sole feels compelled to write a novel between the lines of code and feels it helps them remember what the heck they are doing why does it bother you? Granted 'Good' comments will help someone else down the road. Let us understand people, we comment as a CYA first and foremost and therefore this is an exercise in self preservation; consequently self serving.
-
I hate code comments that say what the code is doing but not why.
/* check for null */
if (someObj != null) {...}Really? Argh!
#SupportHeForShe Government can give you nothing but what it takes from somebody else. A government big enough to give you everything you want is big enough to take everything you've got, including your freedom.-Ezra Taft Benson You must accept 1 of 2 basic premises: Either we are alone in the universe or we are not alone. Either way, the implications are staggering!-Wernher von Braun
I've found that one of the hardest parts of documenting (besides overcoming the initial inertia) is to do what I call philosophical documentation. Don't write what the code does; I can read it and tell you that. Write why you're doing that, why you chose that technique over this one, stuff like that.
-
I hate code comments that say what the code is doing but not why.
/* check for null */
if (someObj != null) {...}Really? Argh!
#SupportHeForShe Government can give you nothing but what it takes from somebody else. A government big enough to give you everything you want is big enough to take everything you've got, including your freedom.-Ezra Taft Benson You must accept 1 of 2 basic premises: Either we are alone in the universe or we are not alone. Either way, the implications are staggering!-Wernher von Braun
My Personal favorite (found in actual production code): // Rather complicated - as in WTF was I thinking?
DB It's a hard life. But somebody's got to live it, if only to act as an inspiration to others.
-
Bah!! find something to complain about for Betsy's sake! If some lonely sole feels compelled to write a novel between the lines of code and feels it helps them remember what the heck they are doing why does it bother you? Granted 'Good' comments will help someone else down the road. Let us understand people, we comment as a CYA first and foremost and therefore this is an exercise in self preservation; consequently self serving.
blow it out your ass. :laugh:
-
Yep. My favorite:
// Declare variables
#SupportHeForShe Government can give you nothing but what it takes from somebody else. A government big enough to give you everything you want is big enough to take everything you've got, including your freedom.-Ezra Taft Benson You must accept 1 of 2 basic premises: Either we are alone in the universe or we are not alone. Either way, the implications are staggering!-Wernher von Braun
-
The company I worked for, many years ago, had to deliver to a valued customer a pre-relase of the new and completely rewritten Fortran compiler: The old compiler could only handle 99 arguments to a function, and this customer had crossed that limit. The new compiler handled 127 arguments, but extending it to 255 arguments was a simple matter. Another company I worked for had to update their linker program: The table of symbols defined and exported by a module could hold only 32767 elements. The customer crossed that limit. By changing the declaration of an index variable from signed to unsigned 16-bit, the linker could handle 65535 exported symbols. I believe the customer never crossed that limit - even though the software had a struct declaration of approx 8300 lines :-D .
Very hard to believe that people would even consider using 50 arguments. When I get a lot of elements I quite often will just set properties since that is easier to keep track of. When I had to pass a lot of data, I would put it in an object and pass the object. When using something like a state pattern I generally have a common area so all states can access common data. I do know that a lot of COM calls can have a lot of arguments, but that is pretty old stuff now.
