|
All of these have significant benefits, but I have to defer to good comments as the best tool for making code maintainable. If I can read a short comment block that explains the purpose of the following code block, it's the best possible head-start.
Intuitive variable names is great; very high on my list, in fact. But I don't want to have to even read the code if I'm not in the right place. I shouldn't have to analyze code, at any level, to determine what the purpose of that code is.
Good coding practices and standards is also great. I don't want to have to weave through a mess of spaghetti just to end up pulling out my hair when it's all done. (Far too little now, as it is, anyway!) But again, do I need to read this code?
I'm my worst critic. I'm working solo on a huge project, and I'm often updating or inserting comments because I want to be able to quickly determine what code I'm looking at, and second, to determine how it works.
|
|
|
|
|
It is not easy to select one but most acceptable when we have one option clear comments that explain every thing.
Whatever you do will be insignificant, but it is very important that you do it
|
|
|
|
|
I'm glad this is making everyone have a bit of a think
cheers,
Chris Maunder
CodeProject.com : C++ MVP
|
|
|
|
|
There are quite a few 'All Of Above' in the 'Optional Text Answers'.
Vasudevan Deepak Kumar
Personal Homepage Tech Gossips
A pessimist sees only the dark side of the clouds, and mopes; a philosopher sees both sides, and shrugs; an optimist doesn't see the clouds at all - he's walking on them. --Leonard Louis Levinson
|
|
|
|
|
If said comments would really be useful, they'd explain enough of the code to make it understandable, right? (would they be useful otherwise?)
though of course heavily commenting obfuscated code is not the smartest thing to do..
|
|
|
|
|
Except for those comments that are packed in on all sides with code.
|
|
|
|
|
It wouldn't be a Useful comment then would it
A useful comment is by definition useful
|
|
|
|
|
Well this is an argument for those form vs function people. You know the ones that I'm talking about. The people who believe that function can be completely divorced of form and still maintain function.
|
|
|
|
|
Don't you watch House - everybody lies.
This is true of comments as well (not always updated when code is changed).
...cmk
The idea that I can be presented with a problem, set out to logically solve it with the tools at hand, and wind up with a program that could not be legally used because someone else followed the same logical steps some years ago and filed for a patent on it is horrifying.
- John Carmack
|
|
|
|
|
I chose "Clear and concise code logic and structure" because it's one of the harder things to correct.
The runners-up are:
"Wise use of Whitespace" can easily be fixed in Visual Studio via "Format Document"
and
"Obvious and intuitive names for variables, classes and methods" can probably be easily fixed in Visual Studio with (global) replacements
|
|
|
|
|
I believe all three of these are equally important. I think it would have been a better survey had checkboxes been used instead of radiobuttons.
|
|
|
|
|
DonDriskell wrote: all three of these are equally important
Yes, but two are easier to remedy.
DonDriskell wrote: checkboxes
Yar, maybe "pick three".
|
|
|
|
|
I agree.
I don't think any of the given answers could be looked-to as THE best way to make code readable. Though Clear and Concise, I think, almost covers two other choices (concise meaning limiting length, as short as possible but no shorter, and clear might reference picking obvious and intuitive names, etc.). I'd add good comments as the other needed item (something more than "set x equal to the function return value" -- and YES, I've seen comments like that in production code).
|
|
|
|
|
We don't all use tools like Visual Studio. I, for one, type all my code by hand. I've seen too many bad pieces of code from visual studio that either aren't xhtml strict compliant, or violate Section 508 and/or WCAG guidelines.
|
|
|
|
|
squeek wrote: aren't xhtml strict compliant, or violate Section 508 and/or WCAG guidelines.
What? I thought we were talking about code.
|
|
|
|
|
VS may clean up horizontal whitespace, but not vertical. As has been mentioned in another thread, vertical whitespace/grouping can help break the code into more understandable subsections within a method/subroutine/function.
As for renaming. VS has a better option than global search and replace. If you want to change the name of an object/variable at it's definition, it can find all actual uses of that object and change the reference without accidently changing another variable that a global s&r might change (i.e. two identically-named local variables in two different methods of the same form/page/class).
|
|
|
|
|
I've been thinking about this a lot lately while doing code reviews... The most readable code seems to use these three practices:
- Descriptive names for functions, objects, methods, variables... I'm not sure whether or not that falls under "obvious and intuitive"; depending on intuition always makes me rather nervous. IMHO, names for variables, complex objects and high-level methods should describe an intended purpose, while low-level functions and simple types should describe what they do / are:
StringArray entryColumns rather than StringArray strings , LogFileWriter rather than CSVWithTimestampWriter , LogFileWriter:: FlushLog() rather than LogFileWriter:: WriteUnsavedEntriesToDisk() ,
SplitCSV() rather than
ParseLogFileLineIntoColumns() , StringArray rather than ParsedLogEntryColumns ... - Short secondary branches within functions / methods. I don't have a problem with the odd 200-line function here and there, provided those 200 lines amount to a mundate description of a linear process. But when it involves numerous non-trivial branches, it becomes a headache. If there is no
else to an if , then the body should be a separate function. If the <span style="font-weight: bold;"><span style="font-weight: bold;"></span></span>else amounts to "indicate an error and leave the function" or an implicit "get to the end of the function without doing anything", then the test should be reversed and the function should be exited as quickly as possible, allowing me to skip past failure/no-op modes when i want to read the code that actually accomplishes something, and avoid digging into the function's logic when i'm analyzing failure modes. Pendantic "one return per function" people should be taken out back and beaten with a sack of goto s. And of course, if both branches are non-trivial, they should each be split into separate functions.
- Judicious use of "Why" comments. This has to be the most-preached, least-practiced recommendation i've ever encountered. The only thing worse than a confusing bit of code with no comments explaining why it is necessary is a confusing bit of code littered with comments describing things that are perfectly obvious from reading the code itself, but none explaining why it is necessary in the first place.
|
|
|
|
|
Shog9 wrote: Pendantic "one return per function" people should be taken out back and beaten with a sack of gotos.
But we don't do that with goto s anymore.
|
|
|
|
|
Logically equivalent conditional blocks still count...
|
|
|
|
|
Psst. They're called exceptions.
Software Zen: delete this;
|
|
|
|
|
Yeah, true that. I can't count the times i've seen a developer who would never stoop to using goto cheerfully breaking out of a nested loop with an exception or a flag or something equally hard to follow.
They do work beautifully for throwing away big chunks of the call stack though. I don't miss longjmp() / signal() .
|
|
|
|
|
longjmp() was the creation of Satan. I had a copy of the XLISP interpreter that was chock-full of those damn things, and it made it a major PITA to debug.
Software Zen: delete this;
|
|
|
|
|
Amen! You probably have a clue as to how many times I'm stuck with figuring out someone's hair brained hops around the code, be it for error or because the person wanted to do it. There are many times I hate being forced into FORTRAN.
|
|
|
|
|
You should write an article about this, if you haven't already!
- S
50 cups of coffee and you know it's on!
|
|
|
|
|
I would have put #3 as #1. If #3 is good, I can live with crappy names, functions, and anything else. A good tool can give you new names. A low-level programmer can shorten your functions, but no one can figure out or reverse engineer what "what's his name" was smoking or thinking at the time he wrote the code!
|
|
|
|