Archive

Archive for August, 2008

More on Naming Conventions: My Naming Heuristics

August 30th, 2008

Following a hard rule for naming conventions in software development is difficult; it’s always a compromise between how things were named in the past and where things are going in the future. Other dependencies like the size of the project, the number of developers, and the environment you’re developing in play important factors. In short, there’s never a great naming rule, but here’s my general (heuristic) approach to naming.

My heuristic approach to naming conventions:

New Development / Greenfield Work:

  • Follow the conventions of the language, or the standards used within the larger community, and pay attention to the API. For example: If you’re programming in .NET follow the naming conventions outlined in MSDN, in JavaScript look at the DOM API, in CSS look at the definitions.
  • If a formal naming convention exists for the organization and these conventions makes sense (they aren’t too far off the language APIs) then follow them. If it feels like the naming conventions were created in the dark ages by a very-very senior COBOL Developer then start asking questions.

Maintenance / Brownfield Work:

  • Follow the conventions of the existing code if you’re modifying an existing module.
  • If you’re creating new modules then consider following the conventions of the language and API.

This post was inspired by a podcast by Donald Belcham and Kyle Baley on Brownfield Applications.

Author: Adam Kahtava Categories: Programming Languages, Software Tags:

Cross Language Naming Conventions: Avoiding Verbosity In The Presentation Layer

August 29th, 2008

Most languages and technologies used in web applications come with their own unique naming conventions – which is unfortunate, but necessary, because diversity is important. Languages like JavaScript and PHP use camelCase, CSS uses-hyphenated-delimiters, and ASP.NET / Java / and the like adhere to the conventions used in their respective libraries and frameworks. Managing the different naming conventions in a web application can be difficult, but with discipline, embracing each language’s conventions can provide some great benefits.

A common mistake I’ve made in the past, was trying to make all languages adhere to a single convention. As a budding PHP / ASP developer I took the-single-convention-for-all-languages approach. In retrospect, I used this approach because I didn’t completely understand the language I was using, and in order to compensate for this lack of knowledge, I’d try to meld the languages into the mental model I understood best. This was a mistake.

Today, I find that working with the conventions of the language facilitates re-use (experts in the language understand what I’m doing), promotes portability (modules can be used across projects regardless of server-side technologies), encourages global collaboration (open source modules and plug-ins can be easily consumed and contributed to), and helps to a nurture a more maintainable application (developers from other language domains can easily maintain the application with a relatively small learning curve). Like a carpenter working with fine material, I embrace working with the grain of each language. It’s also fair to mention that breaking free from the monocultured (one-size-fits-all) approach to naming conventions provides a broader perspective, and also makes your development skills more universal – it might even open the door to different development domains in the future.

Then there’s the discussion on name length, verbosity, and using meaningful names. Steve McConnell suggests that the optimum name size for a variable or function is between 8 and 20 characters (Chapter 11, Code Complete), but with tools like ReSharper (for renaming / refactoring etc…) I find myself using names well over 30 characters. So names like GetApproveeTotalFromNamedBasket are a common occurrence in my code. However, like most things, verbosity does need balance (everything in moderation right?). In the business layer, descriptive names are a godsend – they jog my memory as I rediscover what the module I wrote last month was supposed to do. But… in the presentation layer languages (like JavaScript, CSS,  ASP.NET, or XHTML) you may want to reconsider using long descriptive names. Since verbose, long running descriptive names in the presentation layer are passed over the network and can degrade performance. Often times these verbose names are combined together – throw in ASP.NET name mangeling, start hooking in verbose CSS definitions, and then start inserting JavaScript events. All this compounds quickly and result in large page payloads filled with elements like the following:

<div id="ctl00_ContentPlaceHolderForAllTheBestImprotantContent
 _PanelForTheBestReviews"
<a onclick="LinkButtonClick_ThankYouForTakingTheTimeToReadThis();" 
 id="ctl00_ContentPlaceHolderForAllTheBestImprotantContent_
 RepeaterForAllMyFavoriteBookReiews_ctl00_
 LinkButtonMarkReviewAsFavorite"
 class="LinkFormatingCssClass SelectedLinkFormatingCssClass" 
 href="javascript:__doPostBack( 
 ctl00$ContentPlaceHolderForAllTheBestImprotantContent$ 
 RepeaterForAllMyFavoriteBookReiews$ctl00$LinkButtonMarkReviewAsFavorite'
 ,'')">Mark As Favorite </a> 

Note: That mess of code above would fire a JavaScript event then an ASP.NET event. It’s the result of placing an ASP.NET LinkButton, inside a Repeater, inside a Panel, inside a Masterpage, and adding a JavaScript event along with some CSS. We can see that using long names in the presentation layers results in a mess of text. It’s also fair to mention that the ASP.NET MVC Framework lets developers write cleaner presentation code.
Sure, everyone cites premature optimization as the root of all evil, and we do live in a world of gzip file compression and JavaScript minifiers. But… keeping names short in CSS, ASP.NET, and XHTML isn’t hard as long as you’re mindful of the final goal. Smaller names in the presentation layer will reduce the amount of data transferred over the network which increase the performance of the application.

Joseph Smarr of Plaxo.com once said:

Web applications are only slow if you let them get slow – Douglas Crockford, Alex Russell and Joseph Smarr: On the Past, Present and Future of JavaScript [30:00]

My preference (project requirements warranting) is to keep things short and concise in the presentation languages while using longer descriptive names outside the presentation languages. What’s your preference?