It Depends ...

[swatts]

Hello Lovelies,

Sorry it's been quiet too much work to do and too little to say.

Part of that work is doing some on-line mentoring with DSH Workshops and it's a huge pleasure. Coming from the various sessions were the following type of questions...

• What framework is best?
• What is the best way to encourage good designs?
• What processes are best?
• What methodology should I use?
• How should we approach re-use?
• Comments Good/Bad?

and so on.....

These questions were pretty much all answered the same way "It Depends.....".

This does not seem terribly helpful on the surface, but the joy of the group means that we can then dig deeper into the issue.

Here's the most simplistic example of the bunch.

Comments Good/Bad?

I know excellent programmers that put comments all over their code, I also know lots of excellent programmers that view comments as obsolete clutter that can obscure the meaning of the code. So what is the best approach to commenting your sourcecode....

It Depends....

I have a crap super-power and that is the ability to remember all my projects, I can go into software wrote 20+ years ago and remember how it works. So for me comments can get in the way.

Many, many great programmers have different super-powers and some cannot remember code they wrote last week. For them comments are the mental cues they need to get into the sourcecode again.

Also people develop in different ways, some are systematic (Comments-->tests-->Code), but some (me) learn by doing. Both of these approaches work well for the individual.

My final comment on comments is a quote.

"Comments are not there to explain the code to other programmers, code explains the comments to the computer" 

Andy  Harris

So the words "It Depends" lead us to a path of better understanding. I think software engineers should employ it more.

I'll talk more on this with regard to design, methodology and process.

...........................................when I get a free moment.

Lots of Love

[richardscheff]

I use comments for two things.  If I do trial and error and discovery that I need  50ms wait or some other constant I like to say why it is there.  

Otherwise the next programmer won't know why and might remove it.

I also like to use comments to explain a struggle and sometimes a challenge to the next programmer to do a better job.  When we are rushed to complete a project and know the solution is not the best solution, but at least it works.

In the form of "It was written this way because of....The drawback is..... Can you do better?"

[drjdpowell]

I use comments most often for references, such as a link to an online manual, or referring to a hardware PDF manual section (sometimes with cut-and-paste quoting of relevant parts of the section).  Otherwise, I pay more attention to good naming, rather than comments: are the VI names, Cluster items, Inputs and outputs, case-structure cases, etc. named meaningfully and clearly.  I will spend time renaming when the code evolves so that the original names are less than accurate or are too generic.

[Dhakkan]

Ditto here.

My response posted in another of your articles, Steve, may apply here as well?

[swatts]

The point I'm trying to make is that the interesting thing is not what people do, but why they do it.

So extensive comments work brilliantly for some people, not so good for others.

This is a simplistic example of exploring factors in software engineering. Using the words "it depends" starts us down the road of understanding the underlying factors.. 

[Dhakkan]

Ah, yes, I totally missed the point.

You've probably hit upon The Truth (two capital Ts). It is the perfect answer.

And what is The Truth? It depends... 🙂 Just being whimsical with words this evening.

[swatts]

There's not enough whimsy in this sort of thing! I highly approve of it!

[Intaris]

We're all different. What leads to a decision at any given time includes personal preferences, current knowledge, how we view the world, past experiences, brain hard-wiring, blood levels of caffeine and the sum of every moment we have ever experienced, and in some cases even what our ancestors experienced. No wonder "it depends". Not only "It depends" but the sheer number of things it depends ON is incomprehensible.

“Suppose there’s a rooster standing next to you, and there’s a chicken across the street. The rooster gives a sexually solicitive gesture that is hot by chicken standards, and she promptly runs over to mate with him (I haven’t a clue if this is how it works, but let’s just suppose). And thus we have a key behavioral biological question—why did the chicken cross the road? And if you’re a psychoneuroendocrinologist, your answer would be “Because circulating estrogen levels in that chicken worked in a certain part of her brain to make her responsive to this male signaling,” and if you’re a bioengineer, the answer would be “Because the long bone in the leg of the chicken forms a fulcrum for her pelvis (or some such thing), allowing her to move forward rapidly,” and if you’re an evolutionary biologist, you’d say, “Because over the course of millions of years, chickens that responded to such gestures at a time that they were fertile left more copies of their genes, and thus this is now an innate behavior in chickens,” and so on, thinking in categories, in differing scientific disciplines of explanation.”
― Robert M. Sapolsky, Behave: The Biology of Humans at Our Best and Worst

[swatts]

You got it matey!

So here's the kicker, what if we didn't need to know all the variables, just some of them.

Where I'm going with this is ...

I think people rush into an approach to finishing a project (or worse get forced by policy), be it a language, methodology, style or process. But they don't do the work up front as to why those things may or may not work. (I know I've been there)

Take having a company template as an example. Your template might be brilliant for the code you write and the style you write it. But it may be unusable for an equally talented co-worker who's brain is wired different.

So before designing your template it's worth knowing who the audience for the design is and what their use-cases are.

"It works for me, so it will work for you" is really not a given.