Re: My first C# project

Tech-Archive recommends: Repair Windows Errors & Optimize Windows Performance

Bob Powell [MVP] wrote:
>>Is there really a reason for this comment?
Comments in code that isn't hacky for performance reasons are usually a sign that things have gone wrong. Your code should generally explain itself.

You just failed the job interview at my company big-style.

There are more programming jobs than there are programmers. I'll live. :-)

However, you're trying to fill one of those jobs. Perhaps you should think more carefully about demanding that potential employees should use your coding style before they join your company - good programmers adjust their programming style to the corporate environment they're working in, and everybody's style changes with time.

However, with that out of the way, I'll now try to convert you to my way of doing things. :-)

5 years ago, I was really into comments - I was mainly using Java at the time, and was a fan of Javadoc.

One day I did an experiment where I spent about an hour writing some code and then I spent another hour refactoring the code to make absolutely sure that anybody could easily understand it, without using any comments.

I discovered, in a very personal and practical way, that well-chosen variable and method names made Javadoc useless. And I discovered that when I made changes to the code, I didn't have to look through to change all the comments relating to that code (comments that are just wrong plague 'well-commented' code).


*** IMPORTANT BIT ***
I discovered that the best way to make each line of code understandable is to think about readability when you write the line, instead of adding a comment after you've written the code to try to compensate for the fact that it's unreadable.


With practice, I found that I could write easily understandable code in only 10% more time than rushing and writing code 'normally'. Since I didn't need to write and maintain as much documentation, I saved time, and I found that my code was much easier to understand.

In my current 'personal' project (>100KLOC) I have 5 comments.
High-level documentation is stored elsewhere (I use paper for that) and documentation saying what a few lines of code do is redundent if you make sure that those lines express what you're doing in a *clear* way.

Alun Harford
.

Relevant Pages

  • Re: The Schneider Scam
    ... You can't fail somebody for driving, ... him the practice time, or you don't allow him to complete the course. ... I don't know about a dumbell, since I asked you to e-mail me documentation. ... First of all Schneider training isn't free, ...
    (misc.transport.trucking)
  • Re: relative-to-source file names (was: Small, understandable Forth)
    ... Zero existing practice, and no user demand. ... And: Code breaker. ... various operating systems. ... you certainly cannot expect me to read 323 pages of documentation ...
    (comp.lang.forth)
  • Re: Filtering a tachometer generator
    ... Jerry Avins wrote: ... > As for documentation, it has been my practice to write down what needs ... > produce working code from it, ... It has been common practice in the places I have worked not ...
    (comp.dsp)
  • Re: unittest: Calling tests in liner number order
    ... For my major project I've got my own test case extraction ... freedom to be quite useful in thinking about the test case. ... signal that it's good practice to allow dependencies between tests. ... documentation with a caveat that it's not good practice, ...
    (comp.lang.python)
  • Re: microprocessor controlled SMPS
    ... With proper docs an assembler approach can be very ... >The doc must be written while writing code and not as an afterthought. ... I'd like to insert here that C without good documentation is as hard to ...
    (sci.electronics.design)