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?) )
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.
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.
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.
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 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.
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.
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.