|
Unless one goes back to the days of programming with numbers code is just text for a compiler to turn into numbers.
I was always told to comment my code so that others might understand it when I left, but I'm still here.
Now we have a whole plethora of documents to fill which I secretly believe is for the accountants so that they can pretend programmers are doing something to justify their salaries.
|
|
|
|
|
(1) code implementing an algorithm/a protocol stack/ :
It requires special knowledge before understanding the implementation.
Much emphasis is put to optimization rather than readability
(2) OS level ( The kernel )/Device driver code :
Same as above.
+ have to learn the device/machine interface from other sources
Datasheet/Specification/Design document/Technical papers /Books/Literature/newsgroup threads
are must-read before understanding the code.( Not Simply API doc.)
modified 15-Apr-14 3:21am.
|
|
|
|
|
I'd prefer to "Visualise" - therefore pictures are best...on a whiteboard
|
|
|
|
|
Surely someone out there must have some better suggestions?...
"How useful do you find the recent surveys?"
* Vital to my career
* Useful, but I can sleep fine without them
* I am of the opinion that I have no opinion
* Not helpful in the slightest
* The bane of my life, I only come here to complain about how bad they are
|
|
|
|
|
You forgot one:
I only answer for the rep points.
Did you ever see history portrayed as an old man with a wise brow and pulseless heart, waging all things in the balance of reason?
Is not rather the genius of history like an eternal, imploring maiden, full of fire, with a burning heart and flaming soul, humanly warm and humanly beautiful?
--Zachris Topelius
Training a telescope on one’s own belly button will only reveal lint. You like that? You go right on staring at it. I prefer looking at galaxies.
-- Sarah Hoyt
|
|
|
|
|
Go here[^]
Software Zen: delete this;
|
|
|
|
|
Done! 
|
|
|
|
|
So let's see...
Chris has been whacking these together once a week since... let me think. 1999 or so. Quick math gets me to 751 weekly surveys (I should go look it up but I think the math is close enough). Keeping it fresh and original becomes increasingly difficult as you can imagine.
Thankfully the world intervenes here and there with all new material, but in between it's a challenge.
I am sure he's love any and all suggestions you might want to put in!
David
|
|
|
|
|
They do spark conversation though.
Yes this weeks is a very simple survey, and it seems like quite a few people still have an opinion to share on the subject.
|
|
|
|
|
In no sense is code easier to read than text. Consider that you don't have to be an expert in a given language to understand text. Also, we can document intent in text, but the code, just has the code. If there is an error in the code, the intent is obfuscated.
Having said that. The comments associated with code are *never* good (so we can't assume good comments).
We always have to fallback to reading code. Some code is easier to read than others, but it is rarely easy to read code.
|
|
|
|
|
These days I find more errors in my spelling/grammar than I do in my code...
I guess that is due to the strictness in most programming languages as opposed to tyeping a set of wodrs for human consupmtion and geting away wiv it
|
|
|
|
|
"Consider that you don't have to be an expert in a given language to understand text."
Consider that the important is to understand what you just read.
I can perfectly read several languages (English, Portuguese, Spanish, French, Italian) but it doesn't necessarily mean that I can understand all books written in those languages.
And I'm not speaking only about the language, the content and the way it was written also has a huge importance.
"Also, we can document intent in text, but the code, just has the code."
Exactly, there's no misconceptions or misunderstandings. There's no implicit meanings or pre-required knowledge.
If you know the language you can read the code. Now it's just a matter of how the code was written (similar to what I said about the books). But although it can be hard to read, you're sure that everything you need to understand it it right there. 
"The comments associated with code are *never* good"
English comments should describe the intent. If you need specifics you should read the actual text (the code).
"Some code is easier to read than others, but it is rarely easy to read code."
True, and to make it readable we should obey to rules like any other communication language.
On my post here I describe a good head start 
|
|
|
|
|
"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.
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
