|
It would depend on my objective. In either case I could derive the requisite understanding from the code.
Thanks
JD
http://www.seitmc.com/seitmcWP
|
|
|
|
|
I'll scan someone's "text about code" and take it with a grain of salt, then go to the code. There's no rule in physics that says the text representation has to be accurate in any way.
If I need to understand it, I need to be responsible for understanding what it actually is, not what $predecessor says it is.
|
|
|
|
|
There is no rule in physics that says the code will do what the text specification says it should do.
|
|
|
|
|
|
Polymorphism, for instance, is all about lying.
(not to mention Dim instruction of VB6  )
Veni, vidi, vici.
|
|
|
|
|
is obsolete as soon as it's published.
You'll never get very far if all you do is follow instructions.
|
|
|
|
|
Or, "Specifications are obsolete as soon as a programmer has delivered code that fails to implement them".
|
|
|
|
|
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
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
