Psuedo Code
-
I do that in paper before putting myself in front of the computer... Even there are tools like Visio and others I'm faster doing it by hand... Then at the end and depending on the complexity I make the final flowchart in visio and store that in the documentation folder or if it is easier I use that approach you are describing. Whichever is the choice it is always a must to put lots of comments in the code.
[www.tamelectromecanica.com] Robots, CNC and PLC machines for grinding and polishing.
Paper and pen are a lot faster. But just scan the paper and store the image in the documentation folder. Don't waste your time trying to convert it to Visio. Visio is a tool for management types that don't have anything better to do with their time but draw ugly pictures.
-
Yes yes.:thumbsup: As Dave Letterman used to say "Once again, Paul, you've crystallized my thoughts most eloquently"
:laugh:
-
wizardzz wrote:
How many of you hash out the logic of what you are about to write in a comment, then code it?
I actually write the basic logic on paper and mess with it there and then I code it. I can see the events and logic flow in my mind and I know how it will behave, to a point, then code it and inevitably debug it. I once read that if you have to describe in detail what your a function or other code does in comments then you have failed your job as a coder. Your code should be clear as to what it does and how it works in a general level. Now, this was a Microsoft developer that said this so take it for what it's worth. :) I see his point though. If you have a function
ProcessMemberIDwhy do you need a comment that says: This function processes member id's. Pretty silly actually.----------------------------- Just along for the ride. -----------------------------
-
Because, the reader may have no idea what it means to "Process" the Member ID. I certainly wouldn't have a clue based on that function name. What does it mean?
TRK3 wrote:
Because, the reader may have no idea what it means to "Process" the Member ID.
I certainly wouldn't have a clue based on that function name. What does it mean?Read the code. If you don't understand it the first time, then read it again. [edit] Also, I have never worked on a project or a code file without doing some basic leg work to know what it does in the first place; either by someone telling me or finding out myself. By doing this elementary leg work I would have found out what a member id was. Hence the function name: ProcessMemberID...oh, this is where I process the member id that I just learned about through my elementary leg work. No obligatory, worthless, useless, comment is needed. ;)
----------------------------- Just along for the ride. -----------------------------
-
TRK3 wrote:
Because, the reader may have no idea what it means to "Process" the Member ID.
I certainly wouldn't have a clue based on that function name. What does it mean?Read the code. If you don't understand it the first time, then read it again. [edit] Also, I have never worked on a project or a code file without doing some basic leg work to know what it does in the first place; either by someone telling me or finding out myself. By doing this elementary leg work I would have found out what a member id was. Hence the function name: ProcessMemberID...oh, this is where I process the member id that I just learned about through my elementary leg work. No obligatory, worthless, useless, comment is needed. ;)
----------------------------- Just along for the ride. -----------------------------
Yeah, but sometimes the code doesn't actually do what the original programmer intended. Then if you have a comment at the top explaining what the programmer intended and you read the code and see that it doesn't do that, you have a pretty good idea that might be the cause of the problem. On the other hand if there are no comments and you read the code and see something that looks strange to you, you then have to go and examine the whole system to see if the programmer was being really clever or really stupid -- you sometimes can't tell the difference if there is no comments.
-
It's called "documentation", real programmer don't do it.
Its the man, not the machine - Chuck Yeager If at first you don't succeed... get a better publicist
-
I do that in paper before putting myself in front of the computer... Even there are tools like Visio and others I'm faster doing it by hand... Then at the end and depending on the complexity I make the final flowchart in visio and store that in the documentation folder or if it is easier I use that approach you are describing. Whichever is the choice it is always a must to put lots of comments in the code.
[www.tamelectromecanica.com] Robots, CNC and PLC machines for grinding and polishing.
Reminds me of the old days, when you had to schedule computer time at the terminal. Back then, you would write your program or algorithm in code on paper, then when it was your turn to use the computer, you could type it in, save it, and compile it.
-
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
Many times when I have a complex procedure to code, I will make a bulleted or numbered list of what must be done, then fill in below each point, the code to achieve the action. For example:
int TestExample::GetCountOfScansReadIn(void)
{
//1. Initialize data structures
//2. ...
//:
//4. Release resources and memory
//5. Return result.
}Then fill it in (C++ example):
int TestExample::GetCountOfScansReadIn(void)
{
//1. Initialize data structures
m_pScanBoundaries = new ScanBoundrySetting[m_nNumScanIndexes + 1];
m_pScanBoundaries[0].m_llScanOffset = 0;
SCANINDEX* scanIndexes = m_pScanHeader->GetScanIndexes(m_nNumScanIndexes);//2. Get the needed data
for (int i = 0; i <= m_nNumScanIndexes; i++)
{
:
}//3. Release memory
delete [] scanIndexes;//4. Return result
return m_nNumScanIndexes;
} -
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
I usually write an empty shell, and start inserting comments as placeholders for functional blocks within that. It gives me a good target to throw code at when I come back through. I've seen far too much code that was horribly written and near impossible to update and maintain. I try not to leave it like that, at least commenting on anything worthwhile I dicover while going through it.
-
Paper and pen are a lot faster. But just scan the paper and store the image in the documentation folder. Don't waste your time trying to convert it to Visio. Visio is a tool for management types that don't have anything better to do with their time but draw ugly pictures.
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.
-
Reminds me of the old days, when you had to schedule computer time at the terminal. Back then, you would write your program or algorithm in code on paper, then when it was your turn to use the computer, you could type it in, save it, and compile it.
Way oooold times those ones James... ;)
[www.tamelectromecanica.com] Robots, CNC and PLC machines for grinding and polishing.
-
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
-
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.
-
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! :)
-
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.