|
"Consider that you don't have to be an expert in a given language to understand text."
We had to reject an open source package because every piece of documentation, from manual to code comments and variable names, were in French. Too bad - the library had a good reputation, but we needed to add some functions to it, and we didn't master French.
A story from the old days: At CERN, the software developers had access to the source code of the proprietary Sintran OS of the Norsk Data computers. I was told that there were two classes of developers: The inner circle knew the real meaning of the HENTE and FYLLE variable names, used in dozens of places in the OS. To the rest, they were just cryptic letter sequenes associated with the ring buffers. (HENTE means "fetch", the read pointer, "FYLLE" means fill, the write pointer.)
|
|
|
|
|
Text is always easier to read.
Unfortunately text is usually neither accurate nor well-written, so while I always prefer "accurate well-written textual description of the code", I always end up checking the code to guarantee the description matches the code.
|
|
|
|
|
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus vel lacinia tortor. Maecenas viverra dolor non neque viverra iaculis. Donec cursus ligula sed libero convallis pulvinar. Vestibulum sit amet malesuada augue, et ultrices odio. Nulla blandit, ante vel vestibulum vehicula, enim lacus ultricies augue, eu bibendum sem ante sed diam. Suspendisse nulla elit, porttitor eget tellus at, auctor sodales purus. Etiam ac mi vel justo rutrum fermentum ac sed sapien.
Proin volutpat diam vel egestas placerat. Vivamus aliquet quam sed lorem ullamcorper scelerisque fermentum nec arcu. Donec libero tellus, interdum eget magna vitae, commodo consectetur elit. Vestibulum vel gravida tellus. Phasellus tristique vulputate euismod. Quisque vitae risus eget sem fermentum laoreet. Nunc aliquam, lorem semper varius dictum, dui dui fermentum neque, in imperdiet diam elit hendrerit erat. Donec sit amet varius libero. Fusce id diam vitae tortor laoreet elementum. Fusce sed fermentum metus. Integer at facilisis quam.
"If you don't fail at least 90 percent of the time, you're not aiming high enough."
Alan Kay.
|
|
|
|
|
(In case it wasn't obvious - that was an example of text that is not easy to read).
"If you don't fail at least 90 percent of the time, you're not aiming high enough."
Alan Kay.
|
|
|
|
|
I like commenting my methods and classes but no comments are usually found inside methods.
These are my rules:
All names should be self-explanatory.
Fix/avoid typos in your names.
Use camel-case to separate words in your names.
A class comment should explain the global purpose of the whole thing.
If more than one purpose pops up then it's time to Refactor!
A method comment is one line long.
If it takes too much time (or text) to explain, chances are the complexity is too high and it's time to Refactor!
No comments inside methods.
Code inside methods should be simple enough to be easily readable.
Avoid more than 3 indentations inside your methods.
If you're indenting too much, chances are you're doing too many things inside you're method. Refactor!
Misconception 1:
"I don't care about unit testing my application so this doesn't apply to me"
Even if for some reason you don't want to do tests, following these simple rules you'll end up with testable code without any additional effort. Later on you can implement your tests, no worries.
Misconception 2:
"My business logic is way beyond your mundane daily task man, that would never work for me."
This applies to all kinds of business or complexity.
It's easy to look at these rules and say that this is all nice but "on a real software" this isn't feasible.
I've heard it several times but in fact it's quite the contrary. The more complex the more you have to push yourself to organize your code.
Misconception 3:
"This is an existing project, it's too late for this."
This is wrong. It's never too late. Although it's a huge effort, too expensive and even useless to refactor an existing project, my approach is to refactor and write tests as I touch the code.
If there's a bug somewhere, I try to write some tests for the functionality, refactor and fix the code.
If you wrote your tests well, refactoring is much more relaxing because you're sure that is the tests pass you didn't break anything 
Result:
If all went as described above, you won't need to write any text documents to explain your code.
Everything will be plain clear for everyone.
Writing "books" to explain your code is redundant and requires a huge effort to keep both in sync.
Cheers!
Alex
|
|
|
|
|
AlexCode wrote: I like commenting my methods and classes but no comments are usually found inside methods.
My philosophy too. Occasionally, I do have inline comments (usually of the why variety) but my ideal is to have none.
AlexCode wrote: All names should be self-explanatory.
Fix/avoid typos in your names.
Use camel-case to separate words in your names.
Yep.
AlexCode wrote: A method comment is one line long.
If it takes too much time (or text) to explain, chances are the complexity is too high and it's time to Refactor!
Yes. An XML summary comment, say, should just be one line. Put anything else in the remarks section.
AlexCode wrote: No comments inside methods.
Code inside methods should be simple enough to be easily readable.
Yep.
AlexCode wrote: Avoid more than 3 indentations inside your methods.
If you're indenting too much, chances are you're doing too many things inside you're method. Refactor!
Yep. However, I use a dynamic code complexity tool (number displayed next to method as I type) as a guide and strive for cyclomatic complexity < 10. Indentation will then take care of itself, as complexity is likely to break this rule if indentation is too great.
AlexCode wrote: Although it's a huge effort, too expensive and even useless to refactor an existing project, my approach is to refactor and write tests as I touch the code.
If there's a bug somewhere, I try to write some tests for the functionality, refactor and fix the code.
If you wrote your tests well, refactoring is much more relaxing because you're sure that is the tests pass you didn't break anything
That would be my approach. In the absence of unit tests on the project (which appears to be the norm in practice) then refactoring at least to the extent of extracting methods is generally safe enough. Sometimes, depending on the fix/extension required, you actually have to do this in order to make the change cleanly.
Kevin
|
|
|
|
|
I mostly agree, except:
1. If writing code with a public API, use documentation comments - the user shouldn't have to study your code to understand how to use it. Any other approach is really just being too lazy to document your work. Also, if using algorithms, I'll often include a link to the algorithm so the next coder can see my reasoning.
2. "No comments inside methods". I use comments when working around something, for example if an API doesn't work as documented, I'll place a comment there so that the next coder can see the reason I took a "non-standard" approach.
I generally agree to avoid excessive comments, preferring code readability, but there are frequently very good reasons to include them.
"If you don't fail at least 90 percent of the time, you're not aiming high enough."
Alan Kay.
|
|
|
|
|
Rob Grainger wrote: If writing code with a public API, use documentation comments - the user shouldn't have to study your code to understand how to use it.
I agree. I did mention using XML summary comments (these are documentation comments in .NET but I don't know if you're a .NET programmer, so maybe you didn't spot that).
Rob Grainger wrote: Also, if using algorithms, I'll often include a link to the algorithm so the next coder can see my reasoning.
I occasionally do this as well, sometimes it might even be a link to a StackOverflow solution.
Rob Grainger wrote: I use comments when working around something, for example if an API doesn't work as documented, I'll place a comment there so that the next coder can see the reason I took a "non-standard" approach.
Yes, I do this as well.
Rob Grainger wrote: I generally agree to avoid excessive comments, preferring code readability, but there are frequently very good reasons to include them.
My heuristic is that comments should be "as many as necessary but as few as possible."
Kevin
|
|
|
|
|
Well written code is subjective. Almost every developer I talk to says, the code from 6 months ago is crap! What is well written today is out of style tomorrow.
I use comments to put myself or my reader into my mindset and help understand how I was thinking when the code was written. While the actual code may not 100% reflect the comments, its a heck of a start.
Its also interesting that people do Code Katas to improve their skill set, but never talk about documentation Kata to get better at documenting.
If you leave it to common sense, many developers will say it is too simple and doesn't need to be documented, then there is no documentation in a system. I assume that everybody is dumb (including me) and document every method. It really doesn't take that long!
Hogan
|
|
|
|
|
I agree with you that good code is subjective, and as we evolve either technical or in business perspective we look back and see things that need improvement.
But one thing is good code, another thing is well written code. Reading the points I mentioned on my post you see nothing related to amazingly performant and optimized code. It's all about how to present and organize it.
And my code from 6 months ago is as readable as the code from today, but my code from 2 years ago isn't! 
So my point is that if you really respect a good set of coding guide lines, your comments will be minimal and usually only at the class level, occasionally at the method level and never inside the methods.
Applying good naming conventions and breaking your code in small testable pieces will make it self documented.
After all, code is a language. We should be able to organize it to make it readable as a book.
As for documentation, that's another story and has nothing to do with in-line comments.
You have to document your business, your architecture and your APIs, but none of them should live in-line with your code.
Happy coding!!
|
|
|
|
|
Alex,
We'll have to agree to disagree on this.
AlexCode wrote: So my point is that if you really respect a good set of coding guide lines, your comments will be minimal and usually only at the class level, occasionally at the method level and never inside the methods.
I can't ever imagine saying that developers can't comment their code inside a method. I often comment things I'm doing. There is nothing worse than being the new guy and having no comments to provide some context to what's going on inside code. Yes the code is the final answer, but somethings it helps to read the Cliff Notes before you start. Not everybody is a subject matter expert.
Hogan
|
|
|
|
|
I agree with you in the sense that we should always comment.
The thing I don't agree is the comments inside the methods.
Comment the classes describing the purpose of it. You can go crazy here and detail everything that this class is meant to do.
Comment the methods when the name is not self explanatory.
Now, after this, if you feel the complexity of a method is such that it needs inner explanation maybe it's time for a refactoring. Most likely that method is doing a lot of stuff and if you think about making some unit tests on it you won't be able to test a single thing but a whole complex behavior.
Usually the argument for not doing this is that you'll end up with several methods that are only called once...
Ok, I agree, it's not pretty but it's testable and very easy to maintain.
It's the difference between that new guy in the team facing a very complex method with 250 lines of code or the same thing split between 10 methods of 25 lines each.
Or between an IF with 2 ELSE conditions, each with 20 lines of code or each calling a different function.
What I'm saying here is that if we split the code it will be much easier to read making it redundant to comment.
P.S.: This is a guide line not a religion. Keeping this in mind will hopefully put you somewhere in between
Cheers!!
|
|
|
|
|
We used "documentation" to define the requirements. Plain english and "business speak"...that way the business could describe any changes they needed but we also had a description of what the code was supposed to do. Of course that didn't always mean that that was what it actually did  Depends on the field I guess.
|
|
|
|
|
|
I've had numerous discussions at work whether or not to comment and/or document code.
After seeing lots of much documented, but poorly documented code I came to the conclusion that code does not lie while comments might.
Whether or not you are going to read the comments and/or documentation you'll always have to read the code too to see if it actually does what the documentation says (and in my experience it often doesn't).
In a worst case scenario you'll end up with a simple software change that takes hours to fix because you need to change the documentation in numerous places.
I prefer to keep documentation and comments to an absolute minimum and just write clean code that is (hopefully) easy to read.
|
|
|
|
|
I'm with you on this. Clean code is important, but the documentation should be consistent, too.
For example, documenting the fields of a class in the class' comment header is BS, while documenting each field of a class is helpful. If now someone comes and uses a field the wrong way, not the documentation but the code is not clean.
I will never again mention that Dalek Dave was the poster of the One Millionth Lounge Post, nor that it was complete drivel.
How to ask a question
|
|
|
|
|
Certainly, in regard to comments within code, the policy should be if you can express it clearly in code than do that rather than comment it. E.g., an easy technique is to assign conditionals to well-named boolean variables rather than comment them.
I find that while I'm writing code initially I will add section comments to guide my thoughts. Then when the algorithm or method is finished I will refactor it so that, e.g., the section comments themselves become well-named methods. At the end there will ideally be zero comments.
Kevin
|
|
|
|
|
Some people seem to be able to write good code, but present it in such a way that you can't work out what the heck is happening...
Though as a general rule, code is getting easier to read as a result of improvements in the editors we use: auto indent is an absolute godsend!
Those who fail to learn history are doomed to repeat it. --- George Santayana (December 16, 1863 – September 26, 1952)
Those who fail to clear history are doomed to explain it. --- OriginalGriff (February 24, 1959 – ∞)
|
|
|
|
|
Start with documentation then go to code
|
|
|
|
|
... without going into specifics the answer will always be "it depends".
|
|
|
|
|
I think Technical person always like to read code first.
Rating always..... WELCOME
The only reason people get lost in thought is because it's unfamiliar territory.
|
|
|
|
|
I agree. The code is more concise is most cases, and you will only read the comment if the code is really strange / complicated, or doing something stupid for a good reason (squashing exceptions)
My plan is to live forever ... so far so good
|
|
|
|
|
Agree
|
|
|
|
|
In my opininon comments must contains explanation of algoritms and link to sources of information, link to KB and focus on theories, not dissertation on the code.
If you program you must understand flow, what you need is a quick presentation of choices taken and who is responsible for business rules.
So both must be read, or (I dont know your experience) MUST BE WRITTEN.
Cheers.
|
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
