Code Generation templates act as your Documentation

[This was originally posted at http://timstall.dotnetdevelopersjournal.com/code_generation_templates_act_as_your_documentation.htm]

On every project, there's an endless list of things you're "supposed" to do, like documentation. I've personally never met a developer who enjoys this, so it usually gets shuffled to the side. One way to simplify documentation is to code generate what you can, because then the code generation template becomes your documentation.

Here's an example: I once was on a project where we had a large amount of base SQL data - things like populating dropdowns, security info, and config settings. Initially this was all done with hard-coded SQL files using tons of insert and update statements. Of course, to explain how to write all those inserts and updates, which tables they should alter, and what values they should set, there was tons of tedious MS word docs. Developers would constantly write failing SQL scripts, then recheck the documentation, fix their scripts, and keep trying until it worked. People always had questions like "Should the 'CodeId' column be set to the primary key from the 'RoleLookup' table? Technically, it "worked", it was just slow, brittle, and costing the business money.

Then, we tried migrating all those scripts over to xml files that got actively code generated into SQL scripts. All of a sudden, in order to actually write those templates, we needed to understand what the rules were. What tables, columns, and rows should be affected? What does an attribute like "active=true" translate into for a SQL script? So, this forced us to flush out all the rules. As time went on, when developers had questions, they could see all the rules "documented" in the code of the generation template (the *.cst file in CodeSmith). People essentially would say: "What happens if I set the entityScope attribute to zero? Oh, the code generator template specifically checks for that and will create this special insert in TableX when that happens. Ah, I see..."

Of course there are many other benefits of code generation, but I think this is an often overlooked one: generating the code from an xml file forces you to understand what you're actually doing. If you need to "explain" how to write code to a code generator, then anyone else can look at that explanation too. This is a similar principle to writing self-documenting code.

This also hit home after I wrote a UI page code generator that was 3000 lines long. I realized that in order for  a developer to create a UI page for that project, they essentially needed to (manually) reproduce whatever that template was doing, which meant that they had to understand 3000 lines of trivia. Anyone with questions on producing basic UI pages could always "look up" how the code generator did it.

Chicago - Codeapalooza was great

[This was originally posted at http://timstall.dotnetdevelopersjournal.com/chicago__codeapalooza_was_great.htm]

I had the good fortune to be able to attend the Chicago Codeapalooza this last Saturday. It was an all-around success - about 30 speakers spread across five comprehensive tracks, hundreds of developers, vendor booths, good community interaction, and more. I'm proud that Paylocity could  be a sponsor. And the event was free.

I've always thought that the big thing about user groups aren't necessarily the tracks (which were good), but meeting other developers in the community. The talent level is always humbling. Several companies were actively recruiting - much better to meet a recruiter in person at a professional event than as one of a thousand random resumes online.

Our demanding field requires continual education, and free, local, interactive events like this are one of the best ways to break the ice, followed up with your own personal study.

Collecting machine information using WMI

[This was originally posted at http://timstall.dotnetdevelopersjournal.com/collecting_machine_information_using_wmi.htm]

Like most developers, I want a fast machine. And like most developers, despite my best efforts, I inevitably find myself coding on a machine that isn't quite fast "enough". One of the things I'm trying to track this down is making my own simple performance benchmark tool (if you know of a tool that works great for you, please feel free to suggest it). And as long as such a tool is running benchmarks, I'd like to collect relevant machine information like memory, disk space, etc...

 

Thanks to Windows Management Instrumentation (WMI), this actually ended up being easier than I thought. There's a lot of different ways to call from the API, here's one example (I saw this template from somewhere else online, cannot remember where):

 

      //Add namespace, in assembly "System.Management"

      //using System.Management;

 

      //Put this code in your method:

      ManagementObjectSearcher mos =
        new ManagementObjectSearcher("WMI_query");
       
      foreach (ManagementObject mob in mos.Get())
      {
        foreach (PropertyData pyd in mob.Properties)
        {
          if (pyd.Name == "WMI_Property_Name")
            return pyd.Value;  //May need to convert type
        }
      }

 

where "WMI_query" is your select query, and "WMI_Property_Name" is the name of the property you want to return. The gist is that you can write WMI queries (a simple string), much like SQL queries, to get machine information. Some sample queries could be:

• "SELECT Free_Physical_Memory FROM Win32_OperatingSystem"

• "SELECT Total_Physical_Memory FROM Win32_ComputerSystem"

• "SELECT Free_Space,Size,Name from Win32_LogicalDisk where DriveType=3"

• "SELECT Name FROM Win32_Processor" //I've seen this occasionally give problems, someone suggested I try the advice from here instead.

Here's a quick tutorial.

Here's the official MSDN reference for WMI queries. There are hundred of things to query on, so a lot of it is knowing which query to write.

 

Note that these queries can be run from other scripting languages, like VBScript, so it's not just a C# thing. I'd expect this to be very popular with most IT departments.

 

It's also useful if you wanted to make a quick tool on your build servers to detect the free disk space, and have a scheduled task kick it off every night, and then log your results to a database. If you have a distributed build system (i.e. several servers are required for all your different builds), then it's a nice-to-have.

Why I still read technical books

[This was originally posted at http://timstall.dotnetdevelopersjournal.com/why_i_still_read_technical_books.htm]

Occasionally I hear a respected developer make the case against books - "Books are dead, use other online resources instead." I acknowledge that technical books do have several limitations:

• They can be very linear, lacking the web's hyperlinks. While books can have cross references, but it's just not the same.

• Books are possibly outdated - books take an average of 1-2 years to get published. Especially with technical books, where the rush is to be first and "catch the wave", books on newer topics may be inaccurate because they were written using the beta of the technology.

• Books can contain information overload - you don't need every chapter in an ASP.Net book to get started (most developers never touch ASP.Net globalization).

• As a book is ultimately printed paper, you can't get a dynamic interaction from a book - i.e. stepping through a source code demo or seeing an animating demo.

• Books physically take up space, and can sometimes be very heavy, such as when you're a consultant in the airport and you need to pack everything into a single carry-on.

• Books can only be in one place at a time - so it can cause problems when you need it at home, but left it at the office.

• This is lame - but sometimes you're on a project where management discourages reading technical books during office hours ("we don't want the client thinking you don't already know what you're doing, read up on that stuff at home") - however the same manager is totally comfortable with you browsing online technical websites.

However, I think everything considered, there is definitely a time and place to use books as a learning resource. Some of these weaknesses can be turned into a book's greatest strengths:

• Books, usually a 200-600 page journey through a dozen chapters, are often more thorough than online tutorials or blog posts. They cover more topics, and show the bigger picture. This gives you a more proactive approach to the topic, as well as inevitably makes you more confident about that topic.

• Books are great for breaking the ice of a new technology because they are a step-by-step journey. You're not scrambling between misc blog posts or tutorials.

• Especially for general topics (basic Xml, Html, C#, SQL, JS), where the entry-level knowledge is pretty stable, a books provides a good introduction and guide.

• Because books are physical hardcopies, they're great when you just want to get away from staring at a laptop screen. Whether it's in an airplane (where practically there's not enough room to pull out a laptop), stepping outside, or even just taking advantage of 5 free minutes (good for reading a page, but barely enough time to even start up a laptop).

• For some personality types, books provide a physical trophy: "wow, look at all those books that I've read through."

Note that books are not intended to be used as your only resource, but rather as one part of a comprehensive learning strategy. Even most tech books today are filled with online links to demos, tools, reference guides, and community groups. I benefit a lot from reading books; I think they're a great tool in one's "learning arsenal".

 

LCNUG presentation on Silverlight

[This was originally posted at http://timstall.dotnetdevelopersjournal.com/lcnug_presentation_on_silverlight.htm]

Yesterday I had the opportunity to present at the LCNUG about Silverlight. It was our third meeting and we had about a dozen people. Given the deep talent, it was very humbling. With a small group of talented people, the presentation became more of a back-and-forth discussion, which is great.

 

You can download a copy of the PPT presentation here: silverlightppt.zip. (I tried using Cliff Atkinson's ideas from Beyond Bullet Points.)

 

Here was the abstract:

Silverlight is a new Microsoft technology to radically enhance the UI experience. Silverlight provides several huge benefits, like a vector-graphics API, programming in a compiled .Net language (like C# or VB), a rich object model, and finally solving the cross-browser problem. We will provide a general overview of Silverlight, with an emphasis on common gotchas and where to learn more.

This is the second time I've been able to present at a user group - previously I discussed MSBuild as an automation language.

Word choice is important

[This was originally posted at http://timstall.dotnetdevelopersjournal.com/word_choice_is_important.htm]

Communication is important, we often use words to communicate, therefore our word choice is important too. Even slight variations in word choice can have very different meanings and connotations. Here are some examples. I'd be curious to hear what examples you've come across in your experience.

 

Wording 1	Wording 2 (More clear)	What's the difference?
I'll get that done by the morning	This job will take 5 hours.	The first implies that you're working all night on it, the second gives you flexibility.
He stepped down from management to be a developer again.	He transitioned from manager to developer.	The first implies that managers are more "important" than developers, which is not always the case. The good companies provide a technical track for senior technical folk, such that transitioning from manager to developer could be a lateral shift, not a demotion.
I've made changes	I've made improvements	Are the changes good or bad?
(talking to a manger) I need this new tool	We need this new tool	Emphasizes that it's not you who needs a "favor" (i.e. a new tool), but rather for the benefit of the team.
This project requires a senior developer	This project requires a skilled developer	The project really needs skill, which doesn't necessarily mean "the developer with the most years of experience."

 

I realize it's just words, but the meanings behind those words are important.

 

[UPDATE]: I am absolutely not saying that one should spin, deceive, or try manipulating people with word choice. No one wants someone else trying to manipulate them with words. The goal is to use clear word choice that clarifies real intention, not use "sneaky" words to trick others or hide important details.

Book: Code Leader

[This was originally posted at http://timstall.dotnetdevelopersjournal.com/book_code_leader.htm]

I'm always fascinated by the difference between average developers, and good developers. Therefore any book that helps explain how to go "to the next level" is going to capture my interest. Patrick Cauldwell's Code Leader: Using People, Tools, and Processes to Build Successful Software does. With a forward by Scott Hanselman, the book lives up to the hype. Patrick sees the big picture, and leverages his experience to explain a dozen concepts used by good developers - the ones who other developers look to as leaders (hence the title). I'm paraphrasing his chapter titles:

1. Buying vs. Building
2. Test-Driven Development
   1. "writing fewer lines of code should never be considered a design goal."  (13)
3. Continuous Integration
   1. "and developer time is always more expensive than hardware" (25)
   2. He emphasizes that while many projects are tempted to offload their build scripts to a junior dev (to free up the senior devs to do something "important"), it's really in the projects best interest to have your best talent create the build process as that immeasurably benefits every aspect of the project.
   3. "Nobody can check in changes at 5:00 p.m. on Friday before going on vacation." (39)
4. When is it done?
   1. "Nothing paralyzes a team faster than trying to reach consensus on every design point." (45)
5. Testing
   1. "Testing is perceived as less 'fun' than writing 'real' code." (57)
   2. "A clean build server is a happy build server." (89)
   3. "One of the most important parts of your strategy should be to demonstrate progress as early as possible." (97)
6. Source Control
   1. I love this: about source control, he mentioned that some are free - "(free as in puppy, not free as in beer)" (112)
7. Static Analysis
   1. He mentions several tools: NDepend, FxCop, Simian
8. Contracts and Interfaces
9. How to limit dependencies - an emphasis on Dependency Injection and Inversion of Control
10. Model-View-Presenter (MVP)
11. and more...

Overall, a very good book. It's filled with tools and practical examples. I think that every dev lead should be familiar with the topics that he discusses.