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.