The classic case of clarity

You're explaining your software design to a senior manager in the company. The manager points out a use-case. You sit there wondering why it wasn't included. He then moves onto seeing your code flow. (Yes, they're smart enough to read code.) You've coded the intended requirement for long hours but overlooked the scenario which is picked to discuss. You sit there dumbfounded. You then start to deviate the topic to hide mistakes. But your manager insists to explain the basic flaw. And you go numb and say, "yeah, it had to be included." Your flaw is pointed out. Right in the middle.

There. Clear sign of poor thinking. If there isn't a clarity of thought, you might end up in a disgusting state that you created for yourself. Be watchful of your words - whatever you utter or argue on, specially during a review process. There are some really fine listeners who can pick the pause in your speech and point out a zillion findings. A contextual break in speech can lead to unimaginable confusions. Then the fights, the blame-games and the bad "work culture" signboard all over erupt.

Another example is handling customer requirements. Until you've drilled through the customer's needs with developing bizarre use-cases, you shouldn't be proceeding. Ask questions. Consult. Let people term you as dumb-minded and a narrow thinker because you've asked. (Actually, they're delighted to answer as a matter of fact. Nobody cares your attitude more than asking questions.) Every use-case should be asked a "why" and not a "what". Develop test-cases of varied range. You have to, HAVE TO lay in your demands very clearly before you open an editor or an IDE. You have to think a step above - how the system is designed, what is the process flow about, how can you point out blokes in every corner of the structure, why are certain components missing and what you can do about in putting them, why isn't the system automated, what can you get from the system to learn about, how can it be made better.. the list goes on. There are times when you might be coding without the objective behind. Continue, but please make sure to have this on top of your list of "why" questions.

But most of all, have a clear thought with a sensible and focused approach. You should know where you're heading exactly - be it the quality of roads, the condition of your bike, fuel status and a map. Directions can be misleading. Ask for pointers. If pointers are unclear, ask for more directions. Ask why the pointers were told. Search, search and search. The basics have to be defined well.

And for the questioner problem, make him ask 4-5 questions at a minimum to see flaws in your scripts - First sign of growth towards excellence.

Comment properly, dude..

The developer's nightmare. If you know how to code well, I salute you (I relatively don't. And I thank Google for every single problem that was solved). But what's a code if it's intention is unclear? Have you seen why the code was written for? What are the arguments in those functions? What are these arguments about? What is the function's return value? Can you explain the logic inside in a simple manner to the reader, in the code itself? Can you keep track of why these functions are used? Can you see what a package's common objective is about? What and why are so many variables doing? Can you explain why the design is that simple or that complex? Can you reduce the complexity? Can you comment smartly?

Because, your code in the company isn't yours alone. It's for whom you work for, either your company or someone else's. Which means, risk of it's image. Which means, it is your responsibility to see how you document the process and design well enough. And the code is going to blow up in due course. Your fellow peers will look into these for references. Make them jealous of the way it is being explained. They will use what you've typed. Make them inspire to follow this pattern. If you can't comment properly, what's the point of coding it anyway?

Get the comment in full speech. No bullet points. No follow up of pending test-cases. No confusions, whatsoever. Strange as it may sound, but do revise them along. They change when the code changes. (I've seen a comment totally different for the code written).

How'd you improve your comment quality? Simply get it reviewed from your boss or a person who gathers requirements and note down their inputs. You'll see the differences in your thinking levels. Trust me, it's a huge gap. Knowing the grammar isn't alone these days. You've to be poetic.

Keep it simple. But not simpler.

No hazy scenarios. Your code (and comments) have to be crisp, thoroughly tested (yes, during the development phase) and simple - Simple means a fellow developer or your code reviewer can get it in a layman's perspective. Simpler meaning the layman will understand it, point blank. Convey the purpose only. Straight and clear. Let's judge it good than having a doubtful/confused opinion. Crisping code requires experience (and stackoverflow) where as crisping comments require common sense - And both aren't tough to achieve. And no ego amid all of this, please.

Keep it simple. Not simpler. Code later. Think first. Let's fail and feel bad now than repenting later.

No wonder why people with a clear mind are successful. Hope the post is clearly put across. Do comment for mistakes. I'd love to hear.