|
Complicated code must be accompanied with Comment, while simple code should be self-explanatory. 
I am also not very sure about the Context(Purpose) of this question.
As for "Article Reading" in community like CodeProject, given that only one choice must be made, code block with appropriate comment will be more welcome for me. Of course, a diagram will be more intuitive for complicated linkages and sequences.
I think result of this survey will be directional for new Writers. (In fact, in my first article posted recently I met with the same problem..(in Implementation section, too many text used?)  )
|
|
|
|
|
Code Project must be a little short on good help. This is not a very deep topic here for developers to give an opinion on. I hope an intern came up with this question 
|
|
|
|
|
Not a bad interview question though - anyone who immediately answers "The Code" or "The Text" should be dismissed from consideration.
"If you don't fail at least 90 percent of the time, you're not aiming high enough."
Alan Kay.
|
|
|
|
|
A complicated algorithm (and I've written a few, optimizing the analysis of failure modes in the topography of redundancy switch rings on communication satellites), anyways, a complicated algorithm cannot be gleaned from code, nor code comments, that specifically describe what is happening in a very localized context.
I have a separate document describing the problem and how the core solution works, along with diagrams and test cases, and the second half of the document describes how the optimizations work. Anybody that touches that code must read and thoroughly understand the algorithms.
So, in summary:
* code: code is code, it describes "what"
* comments: comments, if they're good, tell you the "why", but in a narrow, localized context usually
* text (separate docs, drawings, etc.) should tell you the "how"
There's a lot of wiggle room between comments and text, but for anything complicated, I much prefer a Word document and some Visio diagrams.
Marc
|
|
|
|
|
Perhaps the question would have been better stated as Code vs Prose. Code vs text is ambiguous given that most code is represented via text.
10 PRINT "Software is hard. - D. Knuth"
20 GOTO 10
|
|
|
|
|
|
Clear text indicates intent, it indicates what should be happening.
Code indicates how that intent has been realised. i.e. What is actually happening.
So to some extent it depends on what stage of the SDLC you are at.
How many times have you heard "but that's not what we wanted" as a developer. Sometimes that's the difference between code and text. You could argue that neither should exist without the other.
|
|
|
|
|
This question brings about, in my mind, more than just the idea of how to read something, but more how to write it. By definition, any "accurate and well written" text will be as easy to read as the code, but the real question is writing that accurate and well written text, or simply writing the code. For most of us who would understand the code, we can read it directly, and for those who might not quite grasp a given piece, the nuances of the text may well be missed as well. Furthermore, the code itself could have errors or bugs which alter it from intended use, or changes to functions it relies on, which then require the text to update. No matter how well written the documentation, being able to see the code itself is still essential to bugfixing and expansion.
While comments can make something easier to read, they should be simple things accompanying code, not attempting to replace it in documentation and description.
|
|
|
|
|
(For those who can remember)
| "The difference between genius and stupidity is that genius has its limits." - Albert Einstein | | "As far as we know, our computer has never had an undetected error." - Weisert | | "If you are searching for perfection in others, then you seek disappointment. If you are seek perfection in yourself, then you will find failure." - Balboos HaGadol Mar 2010 |
|
|
|
|
|
When code is lengthy or complex summary text/comment is easy to read
for short code block it's easy to read code instead of comments/text
|
|
|
|
|
If the piece of code does exactly what I need or subset of it, then textual description is enough. That happens rarely. Most of the time, the code do too much and cannot be used without some hacking. That is where I go to details and read the implementation. A correct textual description does not give the details.
|
|
|
|
|
G'day Folks,
I would like to see someone tell me that Hex codes are easy to read, unless you can read and speak the Hex Language, which few can. (must be showing my age telling you this)
This goes for any actual Code parameters and their interpretation. Reading them does not mean that the "Reader" understands them.
Codes may be verbalized, i.e. read like text, however this does not mean that they are Text as interpreted in the meaning of the English language.
Codes are a separate language of their own.
If you object to my “Candour”, read another post !
"BENE DICTUM, BENEDICTE !"
|
|
|
|
|
Hex is easy to read and write - the problem is that the interpretation of the sequence of bytes then depends on so many factors that it will usually be fairly useless.
I think you're confusing "Hex language" (it really doesn't qualify as a language - its a number encoding scheme using base 16) with machine language.
Years ago I used to hand-code in hexadecimal for a Z80 on a Spectrum, but thankfully Assemblers, then C and C++ saved me having to sink that low.
"If you don't fail at least 90 percent of the time, you're not aiming high enough."
Alan Kay.
|
|
|
|
|
G'day Rob Grainger,
HEX is a multi-paradigm programming language that supports both static and dynamic types, and was designed with the core principles of simplicity, readability, versatility and scalability to allow developers to create a diversity of types of computer programs with modern language features, succinct syntax and semantics that are built into the core of the language construct.
http://www.hexlang.org/[^]
I may be silly at times, however never stupid as most if not all programing codes are referred to as Languages, i.e. either Programing Language or Code Language depending of where in point of time you started using them. For me it was 1979 or 1980.
Good Luck with your Programing Language.
|
|
|
|
|
My apologies, I hadn't come across HEX before (as you probably guessed). They could have chosen a less confusing name 
"If you don't fail at least 90 percent of the time, you're not aiming high enough."
Alan Kay.
|
|
|
|
|
Text for the purpose of the code.
Code for the implementation of the text.
But as text is normally not well written and code buggy ... it's a gamble
|
|
|
|
|
|
 Agree.
Don't mind those people who say you're not HOT. At least you know you're COOL.
I'm not afraid of falling, I'm afraid of the sudden stop at the end of the fall! - Richard Andrew x64
|
|
|
|
|
But with the advantage of being more structured and formal. Natural languages (English at least) is terrible at that.
|
|
|
|
|
Have you ever been working in APL?
"Text"???
|
|
|
|
|
The text documentation might be the correct version. If it was written by the process owner, it would be correct. Whereas the code might not follow what the process owner intended.
|
|
|
|
|
Which is the map? Which is the terrain?
Is code "the real thing" (the terrain), with the documentation text being the description of it, the map?
Or is the definition of the problem to be solved (represented by the text) the real thing, the terrain, and the code is an approximation to the real soloution, a map of how the real solution would be?
I have seen too many examples of programmers who treat their code as the hard rock mountain that should not be moved even half an inch - and certainly not because some silly "user requirement" demands it. Users will have to adapt, learn how to use the system as it is built! Change both text and user requirements if it doesn't fit the code.
In most cases, however, the platforms with a marketing focus on customer needs rather than developer preferences will have the greatest commercial success. The text is the master, the terrain. Code is the approximate drawing, the map. It may take more effort to learn from the terrain, but the quality of the information is always more reliable.
|
|
|
|
|
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.
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
