רציונליות ישראל

How to write a good comment?

• Make it short
• Make it clear
• Start with a capital letter
• Are you seriously reading advice about how to use a tool (how to write comments) without discussing the goal of the tool?

Let's start from the top.

Comments are a tool for writing good code.

What is the goal of good code?

Disclaimer: I spent most of my career working on huge projects built by tens or hundreds of human years of programming (not counting QA). This means big teams programming, eating, debugging, and complaining about each other's "bad code" together. I believe my perspective applies to anybody working in a team. Still, your  world might be different. You might be writing a POC or some throwaway script. But I'll assume you aren't.

Any noob programmer can deliver code that works. Sure, he'd have some bugs. Sure, you'd have less. But you'd both have some. And that's ok.

Delivering code that generally works is no big deal. Like delivering code that compiles is no big deal. I hope.

But what happens when somebody finds one of those bugs? Will it take him 2 minutes to fix it? Or 2 weeks? How much prior knowledge does she need to do it in the 2 minute option?

And what happens when somebody needs to add a feature to your code? A feature you didn't expect, and you couldn't expect, and it's totally not fair they expect you to cope with it, but still, will it take 2 minutes to add a new hook or will your code need to be totally rewritten to support this?

THAT is the challenge.

Making the code easily maintainable.

Easy debugging. Easy feature-adding. Easy enough for the intern to do, with not much prior knowledge or experience. Easy enough to do without studying the rest of the code.

And this is the goal of almost any "good code" practice I can think of.

Including comments. Comments are a great tool to make the code easily maintainable.

And here's the best way I found to use them:

Share

• average price for levitra
• precio levitra 5 mg