Poll: Concise or Simple code? 1

[Griffyn]

Hi all,

There's a certain amount of pride one gets from writing some concise code: that is, the least amount of repetitious and superfluous code that achieves the same thing.

I wrote this simple event block attached to a Button

[navy][i]// for automatic syntax highlighting see faq102-6487 
[/i][/navy][b]procedure[/b] TMainForm.OptionsButtonClick(Sender: TObject);
[b]const[/b]
  arg : [b]array[/b][Boolean] [b]of[/b] String = ([teal]'Hide'[/teal], [teal]'Show'[/teal]);
[b]begin[/b]
  TButton(Sender).Caption := arg[TopPanel.Visible] + [teal]' &Options'[/teal];
  TopPanel.Visible := [b]not[/b] TopPanel.Visible;
[b]end[/b];

and then realised that if written like this:

[b]procedure[/b] TMainForm.OptionsButtonClick(Sender: TObject);
[b]begin[/b]
  [b]if[/b] TopPanel.Visible [b]then[/b]
    OptionsButton.Caption := [teal]'Show &Options'[/teal]
  [b]else[/b]
    OptionsButton.Caption := [teal]'Hide &Options'[/teal];
  TopPanel.Visible := [b]not[/b] TopPanel.Visible;
[b]end[/b];

It's vastly more simple, and yet I prefer the first example because, well, I don't know why exactly. Perhaps because the coding will scale better, even though it will never need to. Perhaps because it has a few less characters or 'code' lines.

My question is: Given the choice, which example would you tend to in your projects?

 

[Stretchwickster]

Well written code needs no comment.

Roo, I'm afraid I disagree with you there. If you have to implement some complex logic within a function, for example, no matter how well it is written it would likely be much better understood by yourself (a few years down the line) or by others, if it were commented. Within Delphi, code can only be as well written as the language/IDE allows. Sometimes, if a workaround is the only possible way to overcome a problem, it may not be intuitive as to what the code is doing despite writing the code as well as possible.

Clive

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"To err is human, but to really foul things up you need a computer." (Paul Ehrlich)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To get the best answers from this forum see: faq102-5096

 

[roo0047]

Stretch - LOL My knee-jerk reaction to you post was; "Post me some "complex logic [with comments]" and I'll bet I can rewrite it with all your comments embedded in the code." But frankly, I have enough on my plate already.

After a moment of thought, my response to you is this:

Of course there are exceptions, which is why I precluded my opinion with the 80/20 Rule.

Roo
Delphi Rules!

 

[Glenn9999]

Well written code needs no comment.

Definite disagree. While simple run of the mill code requires no comments if the variable names are made properly, very complex code requires the comments if not to explain what is going on. The most comments I put into a program was something of that nature. It wasn't easy to write or comment. Of course, the problem was that I think no one understood it anyway (and no one wanted to sit down and let me explain it).

The big mistake of most commenters is that they can make comments that are restating the code. I had a instructor too that required *each line* of code to get a comment, talk about nasty reading of code (still have it as I do all my projects that I could keep from day 1 of my programming).

 

[harebrain]

I had a instructor too that required *each line* of code to get a comment

Nowadays this is bunk. Your instructor clung to a relic of best practices from the days of writing in assembly language. Some people do things without knowing why; when they're instructors, they should be dismissed.

 

[Griffyn]

I've been programming for 15 years, with only an introduction to Pascal in my last year of High school, plus as an introduction subject in my tertiary course. And I've always struggled with comments. I think mostly because back when you're learning at school you know that the assignment you're working on is never going to be looked at again by anybody. It's only when you've been programming in a business environment for a few years and you need to make changes to some utility or application that people are using that you kick yourself for not commenting it. I've gone through that only recently, and it's getting easier and more rewarding to spend the time putting in comments and revision history.

I'm curious where people 'are at', so to speak, in terms of how long they've programmed for and in what environments. Perhaps it would explain the differences with people's commenting preferences?

 

[Stretchwickster]

I used to find commenting code laborious because I would try to run-through and comment after writing almost all of the code. I know it sounds obvious but commenting as you code is the best practice to get into, after a short time it becomes second nature.

Griffyn, in answer to your question: I learnt various programming languages throughout my academic studies (GCSE, A-Level and Degree) for 7 years. Over the last 4 years, I've been coding in a corporate environment.

Clive

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
"To err is human, but to really foul things up you need a computer." (Paul Ehrlich)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To get the best answers from this forum see: faq102-5096

 

[harebrain]

I started programming in 1970 in FORTRAN IV and moved on to IBM 360 assembly language that same year. I can't even remember all the environments I worked in. That probably helps explain why I'm so diligent about commenting code: I've seen way too much of it that is inscrutable or just awful and always undocumented.

 

[Glenn9999]

Nowadays this is bunk. Your instructor clung to a relic of best practices from the days of writing in assembly language. Some people do things without knowing why; when they're instructors, they should be dismissed.

I agree with that, but actually this guy wasn't the worst instructor I've ever encountered. The worst one was an instructor that a friend of mine had, and when I tried to help them through, I discovered this instructors requirements were totally ridiculous, and totally counter to what industry was doing (and the other instructors teaching that same class).

Comments used judiciously to explain the non-obvious is generally what I like to see the most when I look at source.

For Griffyn: I wrote my first program 14 years ago as a hobbyist, got a IS bachelor degree, worked in industry for about 3 years, and have been unemployed ever since (but still doing an occasional Delphi program). I've been exposed to Pascal, Delphi, COBOL, SQL, C, and a few other things in that time frame.

That probably helps explain why I'm so diligent about commenting code: I've seen way too much of it that is inscrutable or just awful and always undocumented.

Even in my work time, I've had to modify some code that was so nonsensical and convoluted that comments wouldn't have helped one bit (nevermind it wasn't documented to begin with). I had to start by rewriting a program & comparing output with the old program(s) many times.