Code for the weakest coder

[chronodekar]

We "nearly" (and I mean by a hair) had a flame war over this and I don't want to start one. But this point was made by one of our more respected members here, (I'm not calling anyone out) and I want to start a separate discussion over it.

The ultimate goal of comments/coding standards is to make the code more readable and maintainable. BOTH of these are essential IMO for the lifetime of any code. Especially in a production environment.

To achieve this, one tactic is to avoid globals at all costs. And if they are every needed, they should be difficult/tedious to implement. I agree with this.

But I do not agree with the idea that you should code for the weakest coder. If you do that, we'll end up spoon-feeding everyone. I'd rather target the middle-level coder.

All this is my personal opinion. (And is subject to change with convincing (and peaceful) discussion)

-cd

 

[dinkumthinkum]

I think the general principle to strive for is "referential transparency."

 

[Markbnj]

I'm not even sure how you would go about "coding for the weakest coder." If that means avoiding arcane or needlessly complex expressions where simpler or better understood ones will do, then I would agree with it in principle.

 

[KB]

Comments are easy to standardize on, write them often and be descriptive, don't write a comment that is obvious like:

function doSomething(){} //this function does something

I have never shied away from globals. They are usually given their own class and are named so it is obvious they are global.


I have never heard of "coding for the weakest coder", but based on its description I would never advocate it. How will the weakest coder learn from the strongest, if all the code is written so the weakest would understand it. I have always coded for the strongest developer and the weaker ones then learn how to write better code by reviewing or updating the section of the code the stronger developer wrote.

 

[imported_Dhaval00]

^^ What KB said ^^.

This is another good reason to have design and code reviews - they are, IMO, mini coaching/mentoring sessions for the weakest coders. Of course, your team should be enabled and empowered to ask questions... if the weakest ones are interested in learning and growing, they must ask questions often.

 

[Cogman]

It depends on what the weakest coder can do.

Obviously you don't want to have to comment every single line in your code. However, you code should be clean enough that a good programmer can look at it, without comments, and quickly understand what is going on.
If you have code that looks like
animal->mammal->canine->dog->barfy->bark();
animal->mammal->canine->dog->barfy->pee();
when you could just have something more understandable like this
Dog* barfy = animal->mammal->canine->dog->barfy;
barfy->bark();
barfy->pee();

Then you might need to change some things.

The guy that maintains your code shouldn't have to read all the code to understand whats going on.

 

[troytime]

why have a weakest coder?

 

[Titan]

What language are we talking about here?

In general, generalizing doesn't work.

If I want to throw together a quick PHP page globals will do just fine for one page.

 

[Markbnj]

Originally posted by: troytime
why have a weakest coder?

Someone has to be weakest, by whatever subjective measurement system is in place.

 

[chronodekar]

How do I put this ..?

Ok, first, after reading everyone's reply, I guess "coding for the weakest coder" is a very silly and mis-leading term. Let me try and put things into the context I intended.

I'm talking about coding standards. The general rules that *should* be enforced in any coding house worth it's salt. Depending on where you're coming from you'll find that in some organizations, the rule-set is ridiculously rigid and difficult to keep up with. While in other places, it's as good as non-existent.

Hmm... thinking again, I guess what I really wanted to talk about is the difficulty level of the rule-set involved. There has got to be some kind of structure, but having too much of it results in un-necessary burden. In this scenario, a question comes up, should the rules be relaxed so that a new guy will be able to quickly get up to speed? And if yes, to what level should we allow compromises?

That was what I meant by "code for the weakest coder". Not that you program for a newbie, but structure your stuff so that it won't be too hard to pick up.

I hope I'm making better sense now?

-cd

 

[Titan]

Originally posted by: chronodekar

How do I put this ..?

Ok, first, after reading everyone's reply, I guess "coding for the weakest coder" is a very silly and mis-leading term. Let me try and put things into the context I intended.

I'm talking about coding standards. The general rules that *should* be enforced in any coding house worth it's salt. Depending on where you're coming from you'll find that in some organizations, the rule-set is ridiculously rigid and difficult to keep up with. While in other places, it's as good as non-existent.

Hmm... thinking again, I guess what I really wanted to talk about is the difficulty level of the rule-set involved. There has got to be some kind of structure, but having too much of it results in un-necessary burden. In this scenario, a question comes up, should the rules be relaxed so that a new guy will be able to quickly get up to speed? And if yes, to what level should we allow compromises?

That was what I meant by "code for the weakest coder". Not that you program for a newbie, but structure your stuff so that it won't be too hard to pick up.

I hope I'm making better sense now?

-cd

Oh, OK.

Design coding practices for your house as a process, not as a thing.

If people have checklists they fill out and put someplace when the modify code, covering everything from checkout to review, to checkin, then that is a practice to follow.

Coding standards can only be enforced by 2 things working together:
1) code reviews
2) team leadership

Often, either or both are lacking.

There are no universal programming standards across shops. There are some guidelines, but shop to shop, you need one senior code bastard to keep everyone in line. Sadly, I am too young to be that bastard yet, and we don't have one around my shop.

 

[KIAman]

Ahh, so you meant "new employee" vs "weak coder."

How could a rule-set be considered difficult in any situation? Most coders should be enough process-oriented that changing their coding style to reflect their employer's rule-set should be insignificant. In that sense, there is no "weak" coder, rather an "inexperienced" coder.

I'd say use whatever rule-set most fit the requirements of the environment and assuming the environment isn't asinine, a coder should be able to adapt to the rule-set. Just like any coder can program in any language given the tools and documentation of the syntax.

Thinking about it, if the environment has high turnover, then that might be reason to consider a simpler rule-set... but a good rule-set should be as simple and logical as possible while meeting the requirements.

 

[DaveSimmons]

Most of my comments in the other thread were directed towards maintenance programming rather than weak coders.

If a company is successful it will almost always have a code base for its application that dates back to the first development. Over time, sections of the code mature and will not be looked at for many months or even years between updates. For example our major application at work has code dating back to 1999.

Given that the person doing maintenance may not have looked at a function for a year or more, I see value in keeping the code as legible as is practical, avoiding clever or unusual coding as much as possible.

It isn't a question of whether we can figure out the code, it's how much extra time to we need to spend doing so.

 

[chronodekar]

Originally posted by: DaveSimmons
It isn't a question of whether we can figure out the code, it's how much extra time to we need to spend doing so.

Good point. The more I think about it, the more I feel this is where it all matters. At my organization, the more closer we get to our deadline, the more ... 'lax' we get with coding standards. And the standard itself is pretty vague.

I tried introducing something to follow, but I'm not making much headway so far. The challenge is convincing people to follow practises.

-cd

PS - you aren't the poster I was referring to in my OP. In fact, he hasn't even entered this thread yet. I understand now, about the rule against calling out to anyone. Still it's a moot point, and after all this discussion, I don't think it matters if he replies or not.

 

[Markbnj]

Originally posted by: chronodekar

Originally posted by: DaveSimmons
It isn't a question of whether we can figure out the code, it's how much extra time to we need to spend doing so.

Good point. The more I think about it, the more I feel this is where it all matters. At my organization, the more closer we get to our deadline, the more ... 'lax' we get with coding standards. And the standard itself is pretty vague.

I tried introducing something to follow, but I'm not making much headway so far. The challenge is convincing people to follow practises.

-cd

PS - you aren't the poster I was referring to in my OP. In fact, he hasn't even entered this thread yet. I understand now, about the rule against calling out to anyone. Still it's a moot point, and after all this discussion, I don't think it matters if he replies or not.

The only rule against call-outs that I'm aware of applies to mods doing their jobs. Otherwise, call out all you wish, especially if it's positive.

 

[degibson]

EDIT: Long post warning.

Quite a discussion you guys have here!

Originally posted by: Markbnj
I'm not even sure how you would go about "coding for the weakest coder." If that means avoiding arcane or needlessly complex expressions where simpler or better understood ones will do, then I would agree with it in principle.

As others have pointed out, 'weakest coder' isn't a great notion to begin with. It would be better to not have a weakest coder at all -- to have all members of the team be gurus, Mels in every possibly way, and equally talented according to all possible measures.

However, since not all coders are Mel, I think coding-for-the-weakest-coder is a maintainability practice that advocates code that is simple and obvious.

Originally posted by: Cogman
It depends on what the weakest coder can do.
...

Moreover, the designated weakest coder is not a fixed notion. Its not always Jim, or Bob. Maybe Mel is having a bad day... everybody has idiot moments, and unexpected subtleties can crop up... well... unexpectedly. Defensive/obvious/simple code helps the 'stronger' coders, too, by not wasting their time figuring out what is going on (per more of Cogman's post, below).

The guy that maintains your code shouldn't have to read all the code to understand whats going on.

Indeed, hopefully not. I believe strongly in self-documenting code.

Originally posted by: DaveSimmons
Given that the person doing maintenance may not have looked at a function for a year or more, I see value in keeping the code as legible as is practical, avoiding clever or unusual coding as much as possible.

Agreed.

Originally posted by: KB
I have never heard of "coding for the weakest coder", but based on its description I would never advocate it. How will the weakest coder learn from the strongest, if all the code is written so the weakest would understand it. I have always coded for the strongest developer and the weaker ones then learn how to write better code by reviewing or updating the section of the code the stronger developer wrote.

I think we're actually talking about the same thing: writing solid, readable, maintainable, self-documenting, simple, straightforward, and useful code. In some sense, that is leadership by example for weaker coders.

--> The remaining comments are general, not really replies to anything in particular.

Keeping with the (bad) terminology we've used so far:

*Weak coders (WCs) are more likely to screw up code that is subtle than code that is straightforward.

*Strong coders (SCs) are also more likely to screw up code that is subtle than code that is straightforward, though SCs are less likely to screw up in general than WCs.

*In many coding environments, the SCs have a vested interest in converting WCs to SCs, though education. Doing so takes burden off the SCs, improves the code, and increases the value of the team/company/etc. (there is worry that WCs will replace SCs over time, however)

*One possible measure of coding quality is the length of time it would take an 85-year-old grandmother to understand it (ok, maybe granny goes too far with the analogy -- replace her with a first-year graduate student). There are few reasons to ever write code that requires an explanation beyond comments.

*Considerations from the style guide are important, but more important is the metapoint of the style guide: that code in a particular project/organization should look the same. The human brain is a pattern matching system -- code that looks the same is easier to understand once the brain gets the hang of the rules. For maintenance coding, this often means looking around at the code you're working on and adopting the style that is already here, even if it is different from Hoyle, or inferior to the style that the coder happens to prefer.

* Code reviews: Where to begin? Code reviews are as much a social consideration as a software engineering consideration. Its pretty easy for code review cliques to form, each of which adopts a particular variant of the company's style, and then stagnate (or even become malicious). However, this is at the heart of the point in this thread: all measures of code quality are subjective, and coders widely, strongly, and frequently disagree. However, having someone else look at your code is extremely valuable, especially if that other person is at a significantly different level of competency (i.e. WC+SC, or SC+WC): WCs find confusing parts of SC's code, SC's find wrong parts of WCs code. SC+SC yields fewer changes at review-time, as SCs are better at defending their practices. WC+WC misses obvious problems (maybe).

 

[JACKDRUID]

people get old...as they get old they get weak, physically and intellectually.

in addition, the fundation of OOP is based on the simplest code block, weakest in function. but when you put all of them together, you get a complete, tested program.

I agree with "code for the weakest"

 

[chronodekar]

Originally posted by: degibson
I think we're actually talking about the same thing: writing solid, readable, maintainable, self-documenting, simple, straightforward, and useful code. In some sense, that is leadership by example for weaker coders.

I'm glad you replied degibson, yours was the post that made me start this thread.

And you state your position very nicely. I agree with all of it. The only nit-picking I have is the phrase "Coding for the weakest coder". As you've stated, it describes things very nicely, but as others mention, it can be interpreted in other ways too.

We need another phrase for it. What comes to mind is "Keep It Simple Stupid". But, ... its used too often everywhere.

Something else, so we can distinguish AT members everywhere. Any suggestions guys?

-cd

 

[degibson]

Originally posted by: chronodekar
... The only nit-picking I have is the phrase "Coding for the weakest coder"... We need another phrase for it ... Any suggestions guys?

Any Cryptonomicon fans out there? Dwarf/Elf/Wizard ;-)

 

[chronodekar]

Originally posted by: degibson
Any Cryptonomicon fans out there? Dwarf/Elf/Wizard ;-)

First I heard of it. wikipedia

Is it worth reading? Or is this a new World of Warcraft slang that I haven't heard about?

-cd

 

[EricMartello]

Originally posted by: chronodekar
We "nearly" (and I mean by a hair) had a flame war over this and I don't want to start one. But this point was made by one of our more respected members here, (I'm not calling anyone out) and I want to start a separate discussion over it.

The ultimate goal of comments/coding standards is to make the code more readable and maintainable. BOTH of these are essential IMO for the lifetime of any code. Especially in a production environment.

To achieve this, one tactic is to avoid globals at all costs. And if they are every needed, they should be difficult/tedious to implement. I agree with this.

But I do not agree with the idea that you should code for the weakest coder. If you do that, we'll end up spoon-feeding everyone. I'd rather target the middle-level coder.

All this is my personal opinion. (And is subject to change with convincing (and peaceful) discussion)

-cd

Avoid globals? LAWL NO By not using them you'd be wasting memory by duplicating data that would otherwise be shared between the main app and the function or class that requires the data.

If more than one person is working on code, before anyone writes any code you should all agree on conventions to be used throughout the app. This means that when all is said and done, the code from each contributor should be structured, commented and formatted (indented) in the same way. This isn't really a question about programming techniques - it's more like make sure that the people involved are competent enough to do the work they're assigned.

 

[degibson]

Originally posted by: chronodekar
Is it worth reading? Or is this a new World of Warcraft slang that I haven't heard about?

Hmm... debatable. It is extremely long. Its nominally a novel about cryptography, though it tries to teach the reader a bit about computers along the way. There is a taxonomy of people presented in the book: Dwarves are workers, Elves are savants, Wizards are masters of the art. (I think there is a fourth category, but I forget it now).

It is, however, unrelated to WoW.

Originally posted by: EricMartello
Avoid globals? LAWL NO By not using them you'd be wasting memory by duplicating data that would otherwise be shared between the main app and the function or class that requires the data.

Wow. It has been a while since I heard someone actually care about memory size. Bravo.

However, thats why we have pointers. They don't need to be globals to enable sharing between modules.

There is another way to look at the save-memory argument wrt globals: Global variables occupy space forever. Scoped variables and heap variables do not (or at least need not).

If more than one person is working on code, before anyone writes any code you should all agree on conventions to be used throughout the app...

Oh I agree entirely. For groups that are lucky enough to start from scratch, this is certainly the best way to proceed. But for work on code that already exists, we have the monkies, the bananas, and the firehose.

 

[Markbnj]

Originally posted by: EricMartello

Originally posted by: chronodekar
We "nearly" (and I mean by a hair) had a flame war over this and I don't want to start one. But this point was made by one of our more respected members here, (I'm not calling anyone out) and I want to start a separate discussion over it.

The ultimate goal of comments/coding standards is to make the code more readable and maintainable. BOTH of these are essential IMO for the lifetime of any code. Especially in a production environment.

To achieve this, one tactic is to avoid globals at all costs. And if they are every needed, they should be difficult/tedious to implement. I agree with this.

But I do not agree with the idea that you should code for the weakest coder. If you do that, we'll end up spoon-feeding everyone. I'd rather target the middle-level coder.

All this is my personal opinion. (And is subject to change with convincing (and peaceful) discussion)

-cd

Avoid globals? LAWL NO By not using them you'd be wasting memory by duplicating data that would otherwise be shared between the main app and the function or class that requires the data.

I haven't used a single byte of global data, other than the occasional constant, in close to 20 years. Everything that's shared is either at class scope or passed in.

 

[JACKDRUID]

Originally posted by: EricMartello

Avoid globals? LAWL NO By not using them you'd be wasting memory by duplicating data that would otherwise be shared between the main app and the function or class that requires the data.

by using globals, you lose flexibiliity of having a temporary copy of data for data validation purposes.

it also breaks OOP paradign.

 

[degibson]

Originally posted by: Markbnj
I haven't used a single byte of global data, other than the occasional constant, in close to 20 years. Everything that's shared is either at class scope or passed in.

How about cout? cerr? errno? stdout?
I'm not just bringing these up to be a smartass -- I really do think there are legitimate times to use globals. But they're very, very rare.

(admittedly, some of those are only spiritual globals, since they belong to namespace std)

Originally posted by: JACKDRUID
by using globals, you lose flexibiliity of having a temporary copy of data for data validation purposes.

I disagree on this one. Simply because a variable's primary home is global doesn't mean you can't explicitly make a copy of it for validation, or otherwise work on a local dataset and then publish to global state. Thats what happens under the cover in many cases anyway -- it is merely more explicit.

it also breaks OOP paradign.

cout again.

Parting word: This post might make me seem pro-global if taken out of context. I am still firmly anti-global -- you can all breathe again.