What makes code good?
-
Currently, I am reading this book: Beautiful Code[^]. I must say that content wise it is one of the best books I have read. I will rank it high up with books: Code Complete, Design Patterns and Refactoring.
Josh Smith wrote:
Thoughtful naming
Agreed! To me intent code should be just be obvious by reading it. If the code adheres to well known patterns things are a lot easier.
Josh Smith wrote:
I think that all non-private members of a type should be commented
The tricky parts always should have comments. But I hate comment clutter. I personally hate XML comments (javadoc is a little better) and I wish if there was an alternative. When you publish an API all public members should be documented but I necessarily don't agree that they should have comments on top of them. For example, I hate comments likes these if they appear everywhere and just convey the obvious. However, for something not very obvious things have to be commented.
public class Employee
{
///
/// Gets or sets the employee name
///
public string Name
{
get {return this.name; }
set { this.name = value; }
}///
/// Call this method to increase the salary of the employee
///
public void IncreaseSalary(double salary)
{
....
}}
Another thing issue I have seen is sometimes you may use a well known design pattern and the meaning may not be obvious to some programmers but programmers who have read the design patterns book may immediately recognize the pattern and understand how the code works. In such a case I think I will prefer programmer education rather than cluttering the code.
Co-Author ASP.NET AJAX in Action
Rama Krishna Vavilala wrote:
Another thing issue I have seen is sometimes you may use a well known design pattern and the meaning may not be obvious to some programmers but programmers who have read the design patterns book may immediately recognize the pattern and understand how the code works. In such a case I think I will prefer programmer education rather than cluttering the code.
It is perfectly normal in all other forms of documentation to refer to other texts, books, manuals, or whatever, so it has always struck me as strange that techies seem so averse to putting such references into their inline code. Why not say something like:
/// This object follows the WoBBliE desigh pattern construction. /// See "Outside the Factory Walls" by Hoot & Annie.That gives the guys the opportunity to educate themselves, so you win on two counts. You don't have to rewrite a book that's already been written, especially inside a code editor. Inline doc is for explaining minute details, not for giving overviews. -
Marc Clifton wrote:
The rest is just style, common sense, and coding rules.
You know what they say about common sense, right... :)
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
Josh Smith wrote:
You know what they say about common sense, right...
I can't understand whay we call it "common", when it's anything but.
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
I agree with your 3 attributes. What makes code good for me may not be the same as what any particular reader may consider good, and others may have better ideas. Whatever is done, doing so in moderation is essential. The only thing in which moderation is no virtue is excellence. That said... Sensible Comments - My comments should allow a professional developer to know what I am doing in code by just reading the comments. That is really helpful 5 years later when I come back to my code to update it. I use a header in each code module that explains the 10,000 ft overview of "this is what I do", along with a change history (when, who, what). I also use a header above each method or property code block that explains the input/output and what the method/property does. If it is intuitively obvious what it does, then I keep the comment short. Very short. In the code, I use short, one-line comments for most chunks of code to explain the process as it unfolds. Longer comments are useful for more complex processes. Even though some languages (VB comes to mind) are more intuitive than other more cryptic languages as to what the code is doing, it won't necessarily be so obvious to non-VB programmers, so I use comments anyway. I usually accomplish the same task that psuedocode does by writing comments describing the process, then coding to it only after I have finished the comments in an object. Don't ignore, nor go overboard with, OOA/OOP - Spaghetti objects are just as bad as spaghetti code. I hate code that I inherit where someone has gone nuts adhering to the tiniest principles of OOA/OOP like some Pharisee running a string from his home so he can walk farther on the Sabbath. Common sense is an uncommon virtue with OO bigots. I hate code where the author has forgotten the practical meaning of encapsulation. I know sometimes processes can be very complex and require a lot of objects, but I remember the KISS principle when creating my OOA. For example, one program I inherited had no fewer than 14 object modules just to do a login - and that is not counting the data access layer. All it needed was an object class for the login business rules and a UI object to login with. Multilevel logging - I like for my app to have a globally accessible log object that my code can use to log things like performance, process steps, user activity, errors, etc. and a setting that tells the log object what to actually write and what to ignore. I can set the log to record o
-
Marc Clifton wrote:
The rest is just style, common sense, and coding rules.
You know what they say about common sense, right... :)
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
... it's anything but.
-- You have to explain to them [VB coders] what you mean by "typed". their first response is likely to be something like, "Of course my code is typed. Do you think i magically project it onto the screen with the power of my mind?" --- John Simmons / outlaw programmer
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
how about some common sense?
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
All good points when considering the implementation of a particular piece of code. Step up a level and I find the best code to be the code that accepts changes the most gracefully without weird side effects and bugginess popping up. Most code is written once and maintained for years afterwards (thankfully, not by the original writers). It often has extra bells and whistles added in over time. So, the ability to maintain and extend it with little effort counts for a great deal. Many would say I'm really taking about design, but I've seen good designs lobotomized by poor implementation to the point that the design cannot be easily extended as intended, so there's clearly a good-implementation component to make a good design work right. I think that component goes beyond good comments, good naming, good library use, etc.
patbob
-
It's simple, really: If I write it, it's good. If you write it, it's probably a bug infested piece of binary twaddle worthy of only temporary residence in the Recycle Bin! On a more serious note, consistency and thoughtful, *logical* naming make a huge difference, as well as a clean design. I've always thought that the pascal code that came with Borland's VCL was some of the cleanest code I've ever seen.
¡El diablo está en mis pantalones! ¡Mire, mire! Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)! SELECT * FROM User WHERE Clue > 0 0 rows returned Save an Orange - Use the VCF! VCF Blog
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
* Good Layout * Avoiding Magic Numbers
Best Regards, Mushq Mushtaque Ahmed Nizamani Software Engineer Ultimus Pakistan "English is my second language; please excuse any grammatical or spelling mistakes"
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
If we develop alone, this isn't quite a problem, we have our own naming conventions and such. When managing a team, even a small team, this represents a bigger problem to be solved. Each team member tend to develop their code on their own way, which end up with an application much like a code rhapsody. It's usually a good practice to document the project consistency guide-lines, not only for code but for the way of doing things like access a database, distribute business logic between assemblies and stored-procedures, etc. Alex
-
Jim Crafton wrote:
If I write it, it's good.
You must have difficultly getting into buildings, considering that your ego is too big to fit through a door! ;P
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
That's why they let him enter via the car park under the building:)
-
Currently, I am reading this book: Beautiful Code[^]. I must say that content wise it is one of the best books I have read. I will rank it high up with books: Code Complete, Design Patterns and Refactoring.
Josh Smith wrote:
Thoughtful naming
Agreed! To me intent code should be just be obvious by reading it. If the code adheres to well known patterns things are a lot easier.
Josh Smith wrote:
I think that all non-private members of a type should be commented
The tricky parts always should have comments. But I hate comment clutter. I personally hate XML comments (javadoc is a little better) and I wish if there was an alternative. When you publish an API all public members should be documented but I necessarily don't agree that they should have comments on top of them. For example, I hate comments likes these if they appear everywhere and just convey the obvious. However, for something not very obvious things have to be commented.
public class Employee
{
///
/// Gets or sets the employee name
///
public string Name
{
get {return this.name; }
set { this.name = value; }
}///
/// Call this method to increase the salary of the employee
///
public void IncreaseSalary(double salary)
{
....
}}
Another thing issue I have seen is sometimes you may use a well known design pattern and the meaning may not be obvious to some programmers but programmers who have read the design patterns book may immediately recognize the pattern and understand how the code works. In such a case I think I will prefer programmer education rather than cluttering the code.
Co-Author ASP.NET AJAX in Action
totally agree, the reason that I don't like the XML approach, is that it encourages this sort of thing, and we're all know who's the most guilty party in this respect. Re use of "patterns" all I would add is that if you're using a well known pattern then say so, either within the member names or in comments.
-
Damn, I must be a lousy programmer. 1)I never pay attention to consistency, becuase I always change my mind. Sometimes In my one page I don't even have the same prefix on the same type of object. 2)I never think much about a name because you can always rename somthing in Visual Studio (even if it does take a while for the program to update all the references) 3) I usually go back and add comments after I'm done just in case I have to update the app in the future. I doubt they are smart though. I always thought what made code good was 1:Efficiency - Meaning the code will scale for a lot of users (web based) and not hog resources (windows based) 2:Conciseness - Not writing 100 lines of code when you only need 10 3:Simplicity - No need to reinvent the wheel. I have seen some smart programmers write stuff that is really complicated just because they enjoy the challenge. 4: Good Class / Database Design - Most apps succede or fail based on the design of your database tables and or class objects.
I didn't get any requirements for the signature
re efficiency - not all software need be scaleable in the manner you suggest, eg I wouldn't want my pacemaker to run over the web, nor would I want it running Windows. re simplicity - depends on what one regards as complicated, I've known programmers who've never understood ternary operators or bitwise operations, yet I find such things usually add to code simplicity. re conciseness - I'd rather maintain 100 lines of code whose purpose is clear and easily understood, than 10 lines of obscure uncommented code. Concise code does not necessarily mean efficient code, a good optimising compiler often generates very efficient object code from what might look inefficient source, lets face it compiler writers are usually smarter than your average VB app programmer. That being said I do wonder whether the incremental compilers that many of use today have much in the way of optimization. I guess my message is good code should permit optimal compiler output. re design - agreed
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
I may have missed it, but what about the code being directed at the right problem. How much code has been written, tested and documented only to find that that the solution it provides isn't what was wanted. No overloading of member names with information available from other sources - eg CustomerNameTextBoxApplicationFormReadOnly or cstnmTBXAppFormRO, not sure which is worse, probably the latter.
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
Josh, I agree with your points and follow the same principles myself. However, in the 36-years I've worked as programmer I've come across some "ugly" code that in some cases was quite "good". Though my first reaction is usually "What the hell is this crap" when confronted with code that lacks comments and proper indentation, after slogging through the mess I've found clever solutions, functions, etc., that I wasn't previously aware of. Clean (design) and coding is clearly better, but some people are messy yet produce code that works. What are you gonna do? I've seen standards come and go and yet the bottom line is still the same. Edward...
-
What do you think makes some code better than other code? I don't necessarily mean "good" in the sense that it is bug-free, that's a pipe dream. What are the most important things to you when working with code? I think the following attributes are always found in code I consider to be good: 1) Consistency - The coding styles, naming conventions, usage of patterns, etc. are adhered to throughout the codebase. If your team prefixes private fields with an underscore, all private fields should start with "_". 2) Thoughtful naming - The names of things should accurately convey their purpose. I find that some of the best programmers I know dwell on a method name, or class name, or field name for a long time if necessary. 3) Smart comments - Too many comments make it difficult to read the code, too few comments force you to read code which could easily be summarized in one sentence. I think that all non-private members of a type should be commented, all types should have a comment explaining their purpose, and any tricky/hacky/weird code should be verbosely commented. What about you?
:josh: My WPF Blog[^] Without a strive for perfection I would be terribly bored.
Programming with Delphi (3.0 to 7.0) as a professionnal since 11 years. 1) Consistency : I agree My procedure names always start by a noun, my function names by a verb. Function name returning a boolean always start by "Is..." 2) Thoughtful naming : Usually my variable, procedure, function names are quite long, but their naming reflects what they really are and Ctrl-C / Ctrl-V keystrokes are used very often. "Sometimes - The names of things should ..." No, not "Sometimes", "Always" ! 3) "any tricky/hacky/weird code should be verbosely commented." That's what I always quote specifically in my code when I think that in a few months I won't remember why I wrote code that way. CHABAT Florent FRANCE