code comments
-
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.
-
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.
Sure, but remember that Fortran in the 1980s didn't have anything remotely resembling an "object" concept - not even anything struct-like. The Fortran you see today has very little to do with Fortran in the second millenium. When the battles around Fortran77 was being with a lot of very far-reaching extension proposals, old guru C. A. Hoare remarked that "I don't know what programming languages will look like in year 2000, but they will be called 'Fortran'!" He ended up being right: When I first time saw a Fortran 2003 program, I honestly didn't recognize it as Fortran at all! The common way of transferring a lot of values to a function was COMMON. A COMMON block was a named, static, unstructured/typeless block of memory. Each user of the COMMON block had his own definition of it - the order and type of variables etc. Think of it as a shared typeless pointer where each module casts the typeless block to whatever it wants (but the block was static, not heap allocated). Of course any sensible system designer would make one set of definitions, to be copied into all modules, but "include"-like compiler directives where not that common then. So if the layout was changed (say, another variable added), the change had to be duplicated in all source files. With statically allocated COMMON blocks as the only viable alternative, and no struct-mechanisms available, it really isn't that surprising that argument lists could grow terribly long.
-
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.
-
Sure, but remember that Fortran in the 1980s didn't have anything remotely resembling an "object" concept - not even anything struct-like. The Fortran you see today has very little to do with Fortran in the second millenium. When the battles around Fortran77 was being with a lot of very far-reaching extension proposals, old guru C. A. Hoare remarked that "I don't know what programming languages will look like in year 2000, but they will be called 'Fortran'!" He ended up being right: When I first time saw a Fortran 2003 program, I honestly didn't recognize it as Fortran at all! The common way of transferring a lot of values to a function was COMMON. A COMMON block was a named, static, unstructured/typeless block of memory. Each user of the COMMON block had his own definition of it - the order and type of variables etc. Think of it as a shared typeless pointer where each module casts the typeless block to whatever it wants (but the block was static, not heap allocated). Of course any sensible system designer would make one set of definitions, to be copied into all modules, but "include"-like compiler directives where not that common then. So if the layout was changed (say, another variable added), the change had to be duplicated in all source files. With statically allocated COMMON blocks as the only viable alternative, and no struct-mechanisms available, it really isn't that surprising that argument lists could grow terribly long.
Unfortunately I do remember FORTRAN 77. It has been so long since I worked with it. I even remember working with the earlier FORTRAN. I think I remember a book called 10 statement FORTRAN that I used. I was not enamored with FORTRAN 77 mainly because it seemed like some Computer Scientists had gotten hold of it and added all this stuff for making it a general purpose programming language and not extending the math capabilities. The one thing that FORTRAN had that made it special was handling of Complex Numbers. I thought that it should have been extended to handle arrays--There were already other languages available for general programming.
-
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.
For sticking to philosophical terms: You say that we shouldn't document the extension, but the intention. Which fits well with the more colloquial use of the term: You document what the program was intended to do, if it was bug free. That is not necessarily what it actually does ;)
-
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...
:omg:
#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.
Exactly
#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
-
For sticking to philosophical terms: You say that we shouldn't document the extension, but the intention. Which fits well with the more colloquial use of the term: You document what the program was intended to do, if it was bug free. That is not necessarily what it actually does ;)
Indeed.
#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
-
Unfortunately I do remember FORTRAN 77. It has been so long since I worked with it. I even remember working with the earlier FORTRAN. I think I remember a book called 10 statement FORTRAN that I used. I was not enamored with FORTRAN 77 mainly because it seemed like some Computer Scientists had gotten hold of it and added all this stuff for making it a general purpose programming language and not extending the math capabilities. The one thing that FORTRAN had that made it special was handling of Complex Numbers. I thought that it should have been extended to handle arrays--There were already other languages available for general programming.
Maybe I misunderstand what you are saying: Fortran always handled arrays, at least from Fortran 2, with 1-based indexing. One fun detail: This 16 bit minimachine (that is, the size of a full height fridge) I was working with in the early 1980s used a 3-word (i.e. 48 bits) floating point format. The machine had an instruction called MIX3, which decremented the value in the accumulator and then multiplying by 3. MIX3 was tailor made for changing the "logicial" (1-based, 48 bits) Fortran index into a "physical" (0-based, 16-bit word) memory address. If you worry about tne "multiplication" being time consuming: It really was an addition of the accumulator, shifted one bit up, to itself, so it was faster than an ordinary add (which required an operand access). Yes, other languages were available - Pascal dates back to 1970, and honestly: From a language design point of view, it is far, far better than the entire C group of languages. (However, it failed in system programming ascpects; a standard Pascal program resided in a single source file. If the standard had included modularization concepts, it should have beaten C to the ground...). What kept Fortran up for so long was "the same old story": Legacy code. Fortran IV was The Standard for offering open source code (open source did NOT start with Linux!). ACM offered a huge collection of several thousand Fortran IV functions for every imaginable mathematical, engineering, or otherwise scientific, operation. I even worked on a machine whose operating system was written in Fortran (in the days when it was considered 'impossible' to write an OS in anything but assembler). I think of old Fortran with no regrets or complaints, and enjoy all those jokes and ways of speech that came out of Fortran. Like "You can program Fortran in any programming language" (to refer to unstructured, bad code). Or "God is real, unless explictly declared integer". And then the beauty from a Xerox Fortran programming manual: "The primary purpose of the DATA statement is to give names to constants; instead of referring to pi as 3.141592653589793 at every appearance, the variable PI can be given that value with a DATA statement and used instead of the longer form of the constant. This also simplifies modifying the program, should the value of pi change".
-
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
John Woods said it best, and the same applies for comments: > Always code as if the guy who ends up > maintaining your code will be a violent > psychopath who knows where you live.
-
John Woods said it best, and the same applies for comments: > Always code as if the guy who ends up > maintaining your code will be a violent > psychopath who knows where you live.
:thumbsup::~ :(
#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
-
Maybe I misunderstand what you are saying: Fortran always handled arrays, at least from Fortran 2, with 1-based indexing. One fun detail: This 16 bit minimachine (that is, the size of a full height fridge) I was working with in the early 1980s used a 3-word (i.e. 48 bits) floating point format. The machine had an instruction called MIX3, which decremented the value in the accumulator and then multiplying by 3. MIX3 was tailor made for changing the "logicial" (1-based, 48 bits) Fortran index into a "physical" (0-based, 16-bit word) memory address. If you worry about tne "multiplication" being time consuming: It really was an addition of the accumulator, shifted one bit up, to itself, so it was faster than an ordinary add (which required an operand access). Yes, other languages were available - Pascal dates back to 1970, and honestly: From a language design point of view, it is far, far better than the entire C group of languages. (However, it failed in system programming ascpects; a standard Pascal program resided in a single source file. If the standard had included modularization concepts, it should have beaten C to the ground...). What kept Fortran up for so long was "the same old story": Legacy code. Fortran IV was The Standard for offering open source code (open source did NOT start with Linux!). ACM offered a huge collection of several thousand Fortran IV functions for every imaginable mathematical, engineering, or otherwise scientific, operation. I even worked on a machine whose operating system was written in Fortran (in the days when it was considered 'impossible' to write an OS in anything but assembler). I think of old Fortran with no regrets or complaints, and enjoy all those jokes and ways of speech that came out of Fortran. Like "You can program Fortran in any programming language" (to refer to unstructured, bad code). Or "God is real, unless explictly declared integer". And then the beauty from a Xerox Fortran programming manual: "The primary purpose of the DATA statement is to give names to constants; instead of referring to pi as 3.141592653589793 at every appearance, the variable PI can be given that value with a DATA statement and used instead of the longer form of the constant. This also simplifies modifying the program, should the value of pi change".
Sorry I was not clear, I should have said matrix operations. Yes they had multidimensional arrays, but not matrix operations. they did add it later. The reason they did was more so that FORTRAN could be better applied to multiprocessor architectures.