Don't you hate it when...

I'm working on a Sunday, so I can vent, right?

Don't you hate it when you're looking at your OWN CODE and going "WTF?!? This shouldn't even compile!!!" I mean, if it were someone else's code that would be expected, because if you're not me then you're clearly an idiot.

Sorry. Couldn't resist. I'm back to puzzling over my own strange code.

--

Tim Wescott 
Wescott Design Services 
http://www.wescottdesign.com

Been there, done that. My code is also more heavily commented and has less "clever" constructs than it did when I was in my 20s.

I'll let you decide if there's a connection between the two. :-)

There's also the additional perspective that maturity brings to the design and code writing process to consider.

Simon.

--
Simon Clubley, clubley@remove_me.eisner.decus.org-Earth.UFP 
Microsoft: Bringing you 1980s technology to a 21st century world

Yup. I've learned to spend more keystrokes saying what I want to say (unfortunately, its geared towards *me* as the audience -- not "others") than mistakenly trying to "optimize source code".

I also am haunted by a mantra from an early compiler design class: "programs" should fit on one page. I am amazed at how often this advice proves helpful!

OTOH, there is the "rotting" of the meatware to consider.

I've learned that "in line"/"in code" documentation is not enough to refresh my memory of what a piece of code is *supposed* to do, its liabilities/limitations, etc. I.e., *why* did I choose this particular data representation (over lots of equivalent ones!) or this particular algorithm... why did I order the tests in this sequence... etc.

So, I write little "tutorials" that let me explain (to myself and anyone who happens to read over my shoulder) the thought *process*... instead of just the *results*.

[Then again, this problem is probably exacerbated by the long timespans involved in many of my designs...]

We've noticed ;-) Sorry, I couldn't help myself...

And folks complain that I'm *still* not clear!! :-/

No problem, it was a former you that was the idiot. Now you have evolved further, hopefully to the better. :-)

--
Reinhardt

When I started writing code for my own company I learned that it pays to treat code like any other document you write. Write it, read it to see that it makes sense. Then read it again after a few days or even weeks. If it is hard to follow when not fresh in your mind, how hard will it be to read when someone else tries?

Even if you can't take the time to pretty up the code, you can at least add some comments to help understand it.

Sometimes I wonder if that is why some people do well with Forth. They take the time to critique their own code and rewrite it if needed. I see that mentioned a lot in comp.lang.forth.

--

Rick

I've tried that. What the posts get met with is requests for

*specifics*:

- What are you trying to do?

- Why do you want to do that? etc.

So, I try to guide folks through my reasons for asking *before* they pepper me with questions that aren't important.

A colleague suggests many folks are incapable of abstract thought; needing specifics to formulate an answer.

[Here's a great question: is suicide justified?]

Another claims that people are just lazy thinkers; needing a fill-in-the-blank question before they can propose an answer.

The problem is not that you don't use enough detail or that you give too much detail, but that you use so many words to fill in all sorts of unimportant detail and even nuance that is just overkill. You don't have to give every aspect of your thinking. Just explain the purpose of the things you are requiring... without overkill.

If you hear from so many people that you use too many words, do you really think they are all wrong? Try changing your viewpoint and maybe you will see it their way.

--

Rick

It takes effort to write a good concise message. (I believe it was Mark Twain that once wrote something like, "I don't have time to write you a short letter, so I am writing you a long one"). The issue often isn't length per-se, but that there are lots of details that don't really matter, but there may still be important points not clearly stated (or lost in the vast sea of irrelevance).

Often, spending the effort to write a clearer question will help lead to the answer of the question, as it make you think more carefully about it.

He's right Don. You should ask everything in Haiku. Or limericks.

--

Tim Wescott 
Wescott Design Services 
http://www.wescottdesign.com

A bright, young designer from Boston Built a smart GPS for his Austin While sending an email The voice prompted female ...

Your turn

--

Rick

While distracted, in Chelsea got lost in

In my job, it's a requirement that any code I create has to be documented 'for dummies'. It's saved me on many occasions, written at just the right level.

--
This email has been checked for viruses by Avast antivirus software. 
https://www.avast.com/antivirus

The point of documentation is to ensure the writer and reader are "on the same page" when it comes to the implementation and rationale.

Early in my career, I considered this to mean "what have I done, here".

Over time, I've learned that this is usually not enough (well, it may be enough to help someone -- perhaps even me -- fix a glaring error or add a little tweak at a later date). I often find myself revisiting old (which may mean MANY years!) code and wondering "Why the hell did I do it like this?" Even to the point of thinking that my skills must have been much *poorer* "back then".

And, start about refactoring the code to bring it up to "today's standards" -- only to discover *why* it was NOT done in the manner I've just set out (i.e., because there is some subtle aspect of the problem that doesn't lend itself to the "better" implementation and that it only becomes apparent after you've coded a fair bit of it).

By removing the bulk of the documentation to off-line "tutorials", I can freely develop each approach in the tutorial and highlight their faults. I.e., illustrate how the *actual* implementation was chosen to AVOID those faults or to allow for hacks/exploits that increase efficiency, etc.

(E.g., the whole "characterization of bezier curves" issue can't be reduced to "in-code" comments -- there's too much information covered, there)

Additionally, source code is a poor vehicle for conveying anything other than "simple text". How do I tell you the difference between (the sound of) a front vowel and a back vowel? OTOH, if I can embed an image of the oral cavity *in* the documentation, you can easily *see* how they are classified thusly. And, if I can accompany that image with audio clips of sample vowels, you can

*hear* their sounds correlated with the particular shape(s) of the oral cavity.

Trying to express this in text only is, at best, ambiguous and, at least, tedious to write *and* read!

[How do I know what "regional accent" a (US) reader suffers from? Or, that the reader is even a native English speaker??]

The availability of the tutorial is, in a sense, a license for me to be skimpy with my in-code comments; I can reference the existence of the tutorial at the top of the source file and, thereafter, just make brief references to portions/concepts that it presents without detailed explanations. (If the reader doesn't want to avail himself of the material in the tutorial, then I don't feel obliged to have to explain it in the sources!)