Psuedo Code
-
Rarely, but sometimes when there is a method that needs to do complicatd things...
"Dark the dark side is. Very dark..." - Yoda ---
"Shut up, Yoda, and just make yourself another toast." - Obi Wan KenobiThat reminds me of a comment I came across lately: // this function is a quite complex one // todo: write detailed documentation for it That was basically the only documentation in an older, 1500 lines class ;)
-
How many of you hash out the logic of what you are about to write in a comment, then code it? Realistically I haven't done this in a while, but just did so I could go over it in writing before coding it all. It is something I did when I was a beginner much more often. How many of you guys find yourself doing this still?
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
Depending on the situation I write psuedocode both before and after the coding: I often program algebraical functions or complicated algorithms. When I do, I first derive the best way to evaluate the various formulae that I need, then type that in as documentation, then translate it into code. This way I make sure that anyone coming after me has a chance to see what kind of computation I was trying to implement, and if either my formulae went wrong, or the translation. In effect, my pseudo code are mathematical equations, with a bit of extra text to explain what principles I used to arrive at them. On other occasions, when I implement some intricate framework magic, I put most of the documentation into the class header and explain what, exactly, this class is meant to accomplish (and sometimes what not!). In a well designed and documented class it shouldn't be neccessary to put a lot of documentation inside the functions. Therefore, in these cases, I ususally just explain the parameter and return values, and sometimes the assumed pre- and post-requisites if they're not obvious. If i put in pseudo code in these classes it will usually only be after the fact, i. e. when I realize the code has become so complex, it's hard to grasp without some explanations. I also do some pseudocoding-after-the-fact when I'm forced to analyze some obscure code and after some effort manage to divine it's intent. Since I spend half of my time analyzing foreign (and poorly documented) code there's quite a lot documentation coming from that venue.
-
Depending on the situation I write psuedocode both before and after the coding: I often program algebraical functions or complicated algorithms. When I do, I first derive the best way to evaluate the various formulae that I need, then type that in as documentation, then translate it into code. This way I make sure that anyone coming after me has a chance to see what kind of computation I was trying to implement, and if either my formulae went wrong, or the translation. In effect, my pseudo code are mathematical equations, with a bit of extra text to explain what principles I used to arrive at them. On other occasions, when I implement some intricate framework magic, I put most of the documentation into the class header and explain what, exactly, this class is meant to accomplish (and sometimes what not!). In a well designed and documented class it shouldn't be neccessary to put a lot of documentation inside the functions. Therefore, in these cases, I ususally just explain the parameter and return values, and sometimes the assumed pre- and post-requisites if they're not obvious. If i put in pseudo code in these classes it will usually only be after the fact, i. e. when I realize the code has become so complex, it's hard to grasp without some explanations. I also do some pseudocoding-after-the-fact when I'm forced to analyze some obscure code and after some effort manage to divine it's intent. Since I spend half of my time analyzing foreign (and poorly documented) code there's quite a lot documentation coming from that venue.
I had recently inherited a project that performs calculations on currency rates. Some of the algo's were about 80 lines long and nothing in the entire project was documented. The guy who wrote it has left the country, too.
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
-
I had recently inherited a project that performs calculations on currency rates. Some of the algo's were about 80 lines long and nothing in the entire project was documented. The guy who wrote it has left the country, too.
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
wizardzz wrote:
The guy who wrote it has left the country, too.
Wise decision! :)
-
TRK3 wrote:
But just scan the paper and store the image in the documentation folder.
Don't waste your time trying to convert it to VisioI love the new quotes! Well, apart from that... I prefer to go through visio as I can modify the document in a future and it occupies less space than a decent picture. Could it be that I'm a little bit pointy haired? :~
[www.tamelectromecanica.com] Robots, CNC and PLC machines for grinding and polishing.
-
wizardzz wrote:
There is not a single line of documentation in the thousands of lines of code in our production software. I got here 6 months ago, so it is out of my control.
It was like they were planning on making it hard to maintain...
See if you can crack this: b749f6c269a746243debc6488046e33f
So far, no one seems to have cracked this!The unofficial awesome history of Code Project's Bob! "People demand freedom of speech to make up for the freedom of thought which they avoid."
That's nothing - I worked on a real big software - 35 million lines of c++ code. The component I had to work on was 1 Millon lines... We were not allowed to write any comments in the code because the build machine wouldn't build the software over night if it had to parse the comments... THAT was hard to maintain!
-
wizardzz wrote:
The guy who wrote it has left the country, too.
Wise decision! :)
Hey actually popped in the office about 2 months ago and asked for his old job back and got a laugh and a NO! I was hired as his replacement and can attest that his work was absolutely horrendous.
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
-
How many of you hash out the logic of what you are about to write in a comment, then code it? Realistically I haven't done this in a while, but just did so I could go over it in writing before coding it all. It is something I did when I was a beginner much more often. How many of you guys find yourself doing this still?
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
After 40 years of coding, I have learned my lesson about 20 years ago and I STILL COMMENT MY CODE!!!! Anyone who doesnt misses a great opportunity of advertising themselves and how well they code AND DOCUMENT! It is a small world and I have run into techs that have seen my code and was hired albeit only once or twice. As a consultant you have to put our name on as many 'finished' works as possible.
-
After 40 years of coding, I have learned my lesson about 20 years ago and I STILL COMMENT MY CODE!!!! Anyone who doesnt misses a great opportunity of advertising themselves and how well they code AND DOCUMENT! It is a small world and I have run into techs that have seen my code and was hired albeit only once or twice. As a consultant you have to put our name on as many 'finished' works as possible.
-
That's interesting, I never looked at it that way.
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
Other than a specification document, that's the one place where you can advertise freely! Most OOP routines never change very much anyway so comments can have a longer shelf life if written generally. Also managers who do code reviews have a higher regard for the maintainability aspect of the code. Usually it distinguishes my skills(in a way) above the employees who never comment at all. It is difficult to express the comments in a way that other coders would understand but hey there's gotta be something difficult/challenging about what we do! PS. After a while you get tunnel-vision and develop CRS syndrome (Cant remember shit) so the comments come in handy.
-
How many of you hash out the logic of what you are about to write in a comment, then code it? Realistically I haven't done this in a while, but just did so I could go over it in writing before coding it all. It is something I did when I was a beginner much more often. How many of you guys find yourself doing this still?
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
wizardzz wrote:
How many of you hash out the logic of what you are about to write in a comment, then code it?
I've been doing this for over 25 years now, and still find it helpful (especially with complicated logic). Then, when I add in the code I push my pseudocode out as line or block comments. As mentioned in other responses, it's usually for my own (in)sanity when I look at the code 6 months later. Curiously, I find that my pseudocode tends to resemble whatever language I spent the most time in at my previous job (except for those two places that I did COBOL, but one of them was equally split with 370 assembler).
Jack Myers