Psuedo Code
-
I used to do that a lot, but not any more. OOP guidelines are to favour shorter methods that do just one job, so really there's not much need for pseudocode comments of something that small. Hopefully, the higher-level methods call lower-level methods with good enough names that the intention is clear. Of course, where algorithms are important, I may still pseudocode, but that's typically on a scrap of paper by the side of the PC. The only place I comment nowadays is generally where: (i) The code does something non-obvious, such as a workaround for a bug, or... (ii) The code exposes an API callable from other modules, possibly written by other dev's - I don't expect them to root through my code to determine how to use it. Again, well chosen method and parameter names can help a lot here.
Rob Grainger wrote:
(i) The code does something non-obvious, such as a workaround for a bug, or...
Agree.
----------------------------- Just along for the ride. -----------------------------
-
-
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.
Joan Murt wrote:
I'm faster doing it by hand...
:thumbsup:
----------------------------- Just along for the ride. -----------------------------
-
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
if it's a long process, sometimes i'll comment each step first and then fill in the code. it rarely survives the first pass, though. unless i'm following an algorithm from a cookbook, just typing the code brings up issues i didn't consider when writing the comments.
-
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 do it... it makes me think of things more generally rather than getting caught up in details off the back... it makes the actual code writing go a lot faster later on since I don't have to rethink "what's next?".
-
I do it... it makes me think of things more generally rather than getting caught up in details off the back... it makes the actual code writing go a lot faster later on since I don't have to rethink "what's next?".
I feel the same way. It's odd that there seems to be a little bit of dissonance between grasping the logic completely in my mind, and finding the best way to code it. I do tend to code most efficiently when I'm following my own well thought out directions.
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
-
got ya beat, there are 5 comments in the thousands of lines of code in our software..... one of which I paraphrase with single quotes
" 'these things must stay in this order' or bad things will happen"That's the best comment in the whole thing I've been here 3 months so it was out of my control. Going forward however its all on me, I must make sure not to be a hypocrite :laugh: :laugh:Programming is a race between programmers trying to build bigger and better idiot proof programs, and the universe trying to build bigger and better idiots, so far... the universe is winning. A crisis on your part does not constitute one on mine.
gavindon wrote:
" 'these things must stay in this order' or bad things will happen"I like that :thumbsup:
Und wenn du lange in einen abgrund blickst, blickt der Abgrund auch in dich hinein.
-
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
Only if it's really complex, or if I'm making an initial run coding a class and putting method stubs in, and even then, it's more to help me remember my intent than to flesh out the code.
".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
-----
"Why don't you tie a kerosene-soaked rag around your ankles so the ants won't climb up and eat your candy ass." - Dale Earnhardt, 1997 -
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'm a VB.net programmer: my pseudo-code is also my production code :rolleyes: I also add comments when I'm doing something odd or complex. The alternative is spending hours trying to remember what I was thinking when I wrote the code, then hours more trying to explain it to the new guy.
-
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
Depends if I am coding the function immediately or saving for later. If it is for later I will add TODO comments for each of the major steps (if the logic for it is fresh in my head) otherwise I will just add a brief TODO comment on what it needs to ultimately achieve. This is usually only if I don't wont to go off on a tangent thou, which isn't too often. I mean, most the time if I want to add a function, it is cause I need it there and then so it just gets implemented on the spot. Recently, I fleshed a function out with comments and left it because I was only certain about the general requirements and needed to double check the exact data manipulation details before I coded
If my jokes make me laugh, then I have already succeeded with 100% of my target audience
-
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 only really do this in two circumstances. One is if I'm tired and nearing the end of the day and I can see the next hour or so of coding in front of me but just don't have the time to do it. I'll write out the remaining steps in the logic in the form of comments, so the next morning I can pick up the mindset I was in when I finished the previous day. The other circumstance is when I am assigning a task to a junior coder and want to give them a starting point if I don't feel they would have come up with the same logic I did. Especially if they are new to a project, I will often write the method stubs and then the 5 or 6 steps the code needs to take to accomplish the task. I will leave it up to them to actually translate it into the equivalent code. On the topic of comments themselves, I still do write a lot of them. Comments still have a place in defining the interaction of your objects and methods with the larger scope of the project. I never accept comments such as:
// Save the changes
context.SaveChanges();In fact I rip those out on sight. Instead, comments should not address "what" but "why", and discuss the component's part in the overall scheme of things. For example, the point of the following object is not immediately recognizable (took this from a recent project):
public class ColumnContext
{
public int Identifier { get; set; }
public int Date { get; set; }
public int Value { get; set; }
public int Weight { get; set; }
}But the same thing with comments becomes:
// The column headers in the data worksheet are identified by named ranges ("colHeaderValue", etc.) This allows the user
// insert columns, move them around, etc., and we can still identify where the data is. The ColumnContext class stores
// the result of our looking around to see where the data is actually located and acts as a map between the logical
// columns and their physical column numbers in the worksheet.
public class ColumnContext
{
public int Identifier { get; set; }
public int Date { get; set; }
public int Value { get; set; }
public int Weight { get; set; }
}Granted, you could have just Find Usages'd and looked around the code at what this object is being used for... but then you could say the same thing for any commented code. Another example, this time some annotations about the method's usage in the overall scheme of things:
// Take a filename for an uploaded KPI data worksheet and return a POCO contain
-
I used to do that a lot, but not any more. OOP guidelines are to favour shorter methods that do just one job, so really there's not much need for pseudocode comments of something that small. Hopefully, the higher-level methods call lower-level methods with good enough names that the intention is clear. Of course, where algorithms are important, I may still pseudocode, but that's typically on a scrap of paper by the side of the PC. The only place I comment nowadays is generally where: (i) The code does something non-obvious, such as a workaround for a bug, or... (ii) The code exposes an API callable from other modules, possibly written by other dev's - I don't expect them to root through my code to determine how to use it. Again, well chosen method and parameter names can help a lot here.
Same here:thumbsup:
There is only one Ashley Judd and Salma Hayek is her prophet! Advertise here – minimum three posts per day are guaranteed.
-
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 did in the early days. No more. My feeling now is, if you're going to put that level of effort in up front, then just write some bloody tests and you have an executable specification of what the code does. The point of that comment first approach was never the comments that were left in the code, it was the advanced planning for the next bit of coding. Indeed the kind of comments you write before you write code are exactly the kind of comments that I hate to see in Code. ' Get the Log Filename and Path logFileName = Config.GetLogFilenameAndPath(); ' Open the Log File logFile.Open(logFileName); ' Write the event details logFile.Write("Bored out of my tree"); ' Close the logFile logFile.Close(); etc, etc. You might not go into that level of detail, but the point remains, comments written before code then to focus on what the code does. If the code itself is written properly those are completely unnecessary comments. -Richard
Hit any user to continue.
-
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 do this occasionally. I write the algorithm in fairly plain English text in comments. The code gets inserted betwixt and between the comments as necessary.
Software Zen:
delete this; -
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. -----------------------------
Same here. I have notebooks dating back 10 years. I have the luxury of being the only coder here for the last 10 years. I only comment code sections where bugs were fixed...unless it was something really stupid, then I destroy any evidence of it!
"Go forth into the source" - Neal Morse
-
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.
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
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."
-
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."
-
The job ain't done until the paperwork is finished...
Real men don't use instructions. They are only the manufacturers opinion on how to put the thing together. Manfred R. Bihy: "Looks as if OP is learning resistant."
Hear, hear.
Daniel Vaughan Twitter | Blog | Microsoft MVP | Projects: Calcium SDK, Clog | LinkedIn
-
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
My comments don't usually take the form of pseudo code. The real code is usually more than enough. Who made the change, when they did it, and why are usually about it. For new function or module definitions, sometimes, in addition to basic parameter and function descriptions where needed, I put in use case examples; so, people will know how best to call the thing. The examples are usually excerpts copied from real code that calls the new functionality. After all, why fake the code in a comment, when you can show them the real thing?
-
My comments don't usually take the form of pseudo code. The real code is usually more than enough. Who made the change, when they did it, and why are usually about it. For new function or module definitions, sometimes, in addition to basic parameter and function descriptions where needed, I put in use case examples; so, people will know how best to call the thing. The examples are usually excerpts copied from real code that calls the new functionality. After all, why fake the code in a comment, when you can show them the real thing?
Well, for me, it's usually to hash out a big picture idea first. I don't do this instead of comments. Sometimes it's easier for me to analyze my logic or algorithm before taking the time to write the actual code.
"I have a theory that the truth is never told during the nine-to-five hours. " — Hunter S. Thompson
