Author

I am Joannes Vermorel, founder at Lokad. I am also an engineer from the Corps des Mines who initially graduated from the ENS.

I have been passionate about computer science, software matters and data mining for almost two decades. (RSS - ATOM)

Meta
Saturday
Nov112006

A few tips for source code versioning (do not drive your co-workers mad)

Source control management (SCM) is a technical matter as well as a good practice matter. Here is a small list of tips that I have found quite useful in practice.

A good commit is like a good paper:

  • It starts with an evocative title. Ok, there is no title in SCM but there are comments provided while committing. If your SCM comment is not clear, then how do you expect your co-workers to keep track of what you are doing? A good title takes time and so does a good SCM comment. Do not rush your commit omitting the SCM comment.

  • It has a clear self-contained content and focus. If you start working on many different files, you may end-up with a large commit covering many unrelated aspect of your software. Such a commit is hard to read for your coworkers because there is no focus. A lot of things are going on but nobody can really tell what did change and what did not.

  • It goes right to the point: Insignificant elements are left outside the scope of the article. Do not commit a file if the changes have no purpose whatsoever. Such situations arise easily when you've just added or removed a few blank lines.

  • The SCM comment is your title, eventually your headline, but it's definitively not the content of your paper. In particular, do not use the SCM comment to raise questions or ideas. Those elements must be handled directly in body of your commit, i.e. the committed files themselves. The SCM comments will be quickly lost in the SCM history, but the ideas/suggestions must stay until implemented or discarded.

Wednesday
Nov082006

A small developer-oriented PowerShell wish list

I have just started to use the PowerShell a few days ago; and I am more and more impressed by the work that have been done by the MS folks. Yet, being a developer, I have the feeling that many aspects of PowerShell still need to be polished.

  • Too bad that there is no Visual Studio project templates for CmdLets. Providing an hello-world CmdLet with its associated SnapIn would really make the life of the developers easier, smoothing the learning curve.

  • Implementing a CmdLet is so full of traps, I would really see some strong FxCop support to help the poor developers to avoid the most obvious errors.

  • A few objects dedicated to CmdLet unit testing. Currently, in order to get a CmdLet unit tested, you have to resort to some custom tricks. A small dedicated & embedded testing framework would ensure that the CmdLet environment is simulated in a proper manner.

  • A dedicated MSBuild task to include whole PowerShell scripts (using the CDATA); the MSBuild properties being inherited as PowerShell variables. MSBuild and PowerShell do have very complementary design; integration would be the key to leverage both of them.

  • Some XSLT convertion to transform the .Net documentation produced by the compiler into CmdLet Help documentation. In the current situation, the CmdLet documentation end-up duplicated in the .Net source and in the CmdLet XML documentation file.
Wednesday
Oct252006

Let's get cosmetic on C# documentation

I am gathering here just a few C# documentation cosmetic tips that I apply in my own projects. I do not pretend to have achieved any absolute truth or any optimal practice with those tips. I just find them convenient when applied with consistency.

  • #region #endregion directives can be great, but caution not to overuse them by putting a dozen of directives within a 200-lines long code file. Indeed, if region makes the code structure more apparent, region also makes the code less proofreadable because you have to open the regions to actually start reading. As a rule of thumb, region directives should only be used for at least 100 lines.

  • XML documentation is great too. But again, Visual Studio makes it quite easy to overuse XML documentation. Basically, with 3 strokes you can generate up to a dozen of lines of empty comments. Yet, if those comments are not completed with insightful content then you're just polluting your code. Here, I define insightful as being any comment that goes beyond the information implicitly provided by the method signature itself. Example: if you have a method named Foo.DeleteUser(Guid userId) do not tell me, that userId is the user identifier. I know it because it's obvious. Tell me what happen when no such user exists. Documentation has to be maintained like the rest of the source code. Useless documentation only makes the code harder to maintain.

  • In the case of the internal project, wrapper methods (methods that basically forward the call to another method) is the kind of objects where it's actually better not to document. Instead, I prefer using a <seealso/> XML documentation reference. Indeed, documenting a wrapper is pretty much like duplicating your documentation. If this documentation is exposed to your customers, then you do not have much choice, you have to duplicate the docs (MSDN are full of replicates), but for the internal development needs, I found such replication far from being cost-effective. Thus I avoid the docs replication through XML references.
Wednesday
Oct182006

Blogosphere quatitative elements, a few slides

Being part of the Corps des Telecoms, I have been assigned for a modest blog study within the scope of a communication course. I have found the subject highly interesting because blogs open whole new directions of research and whole new methodologies. Indeed, contrary to most usual communication events (ex: person-to-person talks), it's potentially possible to retrieve most of the blogosphere content through web crawling intensive methods.

The slides of the talk have been uploaded. Disclaimer: don't take the content for granted, the professor in charge of the communication course was thinking that this talk was a big pile of stupidities from the first slide to the last. My personal opinion is quite different on this matter. Well, I can't make everybody happy.

Saturday
Oct142006

ResxEditor reloaded - version 1.2 released

They were a couple of long standing issues with ResxEditor. Most of them were actually reported as comments on the blog post of the initial ResxEditor release. All of those issues are now fixed. Bug fixes and new features are detailed on the ResxEditor page.

Special thanks to Nick Pasko for carrying most of the work and finding a solution to get rid of the previous cell saving behavior that was driving translators nuts.