Thursday, December 5, 2013

GhostDoc, Conventions and Writing Self-Documenting Code

Given the C# method signature:

        private void CreateImageStreamAndAddImage(
            FileInfo imageInfo,
            int ImageBufferSize,
            ImageStreamInfo streamInfo,
            IPictureUploadService pictureUploadService)

GhostDoc will generate the following xml doc comment:

        /// Creates the image stream and add image.
        ///
        /// The image info.
        /// Size of the image buffer.
        /// The stream info.
        /// The picture upload service.

which, IMHO, is almost perfect! (add should be adds). This conceptually simple trick, a bit of parsing, stemming and grammar, goes a long way towards encouraging method names that clearly communicates what the method does.

This wouldn't be nearly accurate enough if it weren't for the fact that C# (well, .NET in general) ships with naming guidelines. They're illustrated in the language spec, documentation examples and the  design guidelines for class library developers.

The more team development I do the more I appreciate the benefit of conventions designed to aid readability. Team members come and go but the code is always there. Documentation comments tend to rot (easily corrected with GhostDoc but still) but method names last until changed.

Clarity in method naming strikes me as akin to clarity in writing. A well written explanation can be orders of magnitude* easier to understand than a poorly written one. It's just as easy to muddle concepts in print as it is in writing - perhaps this is why it's called writing source code. Throw in teams comprised of members from different language backgrounds and these conventions become even more important (as does one's appreciation for the hurdles being overcome by amazing devs writing in a non-native language!).

No comments :

Post a Comment