Category Archives: Documentation

"Public" API’s

Posted in Best Practices, Documentation, tools by

I have for along time prided myself on writing code that other developers would want to use. It was my brother that actual gave me that definition of good code and i think it is a good way to think of how to write code.

I have recently been using “legacy” code and am constantly amazed that none of the public methods /classes are commented or documented or have argument checks. What I find slightly amusing is the screeds of code that is commented out in certain code files. I have no problem commenting out code while running test etc, but delete before you check it in, that’s what source control is there for! Certainly do not release code with all that crap in there…

If you write c# in the .Net framework you probably use VS. Turn on FX cop.
For gods sake its there to make you a better coder, not to just randomly show arbitrary message at the bottom of your screen. If i am working on a project i prefer the set warning to errors from the start, then the code stays clean.

Use ReSharper. Your code will be cleaner. I am the only one using it at my current place of employment and the HUGE amount of redundant code that shows up is unbelievable! It may go a way to explaining why after 14 week the U.I. was still not up and running.

Use GhostDoc. Its makes commenting a completely trivial task and also helps you name methods in a more appropriate manner. If I notice the comments don’t make sense then instead of rewriting the comment I now rewrite the name of the method till the comment makes sense. The more you use it the less this occurs.

Check your arguments on all public methods. This is call Design By Contract. I basically check everything that isn’t a Boolean.
These things all reduce the chance of you being one of those developers… the one that i curse at as i work with their code.

Look at your code.
Is it clean to look at, with out even reading it?
Can you, at any stage, generate meaningful documentation from your code?
Do you know off the top of your head what the code coverage is likely to be on your current coding project (assuming this is greenfields)? Is it appropriate?

Some colleague I have worked with think this is Gold Plating.
Bullshit. We get paid good money to do our job.
Number one priority is to develop working code on time, sure.
But I believe, certainly as a contractor who may never be seen again, it is also my duty to make it as easy and intuitive for the next guy, of whatever ability, to use, re factor, debug and modify my code.
These practices do not deter from our number One priority. In fact I have found the above implementations, along with TDD, usually mean that you are more likely to handle code once and not have rummage through it again later looking for bugs. And if you do, I guarantee it will be a lot faster than if you had not put these practices in place.

* certainly since I have been a contractor!

False Economies

Posted in Documentation, Unit Testing by

As I get older and more experienced in the IT game some basic truths continue to rear theirs head… One I am currently running into is the idea of not doing some standard practice thing because it will “take to long” or “cost too much money” to do.
I have no problem with not doing some because it is too expensive, however when you are building a business critical application for a publicly traded, Tier 1 company, you had better make sure that those things that you are not going to implement don’t bite you in the ass later.
Documentation and Unit testing should not be negotiable. Especially around business object and other lower level layers. If these layers are not working correctly, how can the layer dependent on these be reliable?
One thing I see more often than I like is not putting enough emphasis on DB design. If you are using a very basic OO model and the DB is literally just a persistence layer then I am all for ORMs. If you have complex set based structures, hire a good DB geek that can architect a proper data persistence approach in terms of DB design and helping with Data Access. Often a developer is not the right person to be doing this.
(I think I have already emphasized this enough on this blog)
Another issue is allowing for future changes. Udi Dahan proposed a design principle which I agree with and employee:
For any classes A and B in a system where both A and B have behavior, A should interact with B through an interface.
The interface which separates two concrete classes should be packaged separately from either of those classes
By employing the strategy above, you allow for the ability to have tests to isolate each “layer”. You also then allow for changing of dependency. As long as the new class implements the original interface, how the business logic occurs is irrelevant. This came up specifically this week with regards to the data access layer. Using this strategy we could investigate different options in terms of the DA, such as using the current implementation, a modified version of the current, an ORM or a Generated layer based on the DB schema. If this had been done earlier it would have take lesser than a minute for each class. Not really a huge time loss there.

I dont take all of this as bad things, it is learning from mistakes, whether they be yours or others. The point is we need to learn from them so we can find ways to avoid or fix future encounters.

Currently Playing with Castle stuff and GhostDoc

Posted in Castle, Documentation, MVC, tools by

New (to me) stuff i have been playing with:

As well as the CAB/ SCSF stuff ihave been working on at work, I have been playing with AR & AW at home. They dont really go with my normal views on enterprise level data access, however in my vague attampts to broarden my horizons I have started to dable in their worlds.

Benefits:

  • Easy to read code. As all the DA is under the hood its code creates the illusion(?) of clearer code.
  • Easy to create Business entities and DA, just drag and drop.
  • Seperation of Business entities from UI

All of this can be done with Code smith, however I thought I would look at this as it is another “string to my bow” so to say. I am currently building a smalll web app from it to see how well it work under light load.

I can see these tools beign great for very basic web sites. Get someone who understands the data requirements to build a DB and AR classes then just palm it off to the UI guys as the model aspect of an MVC set up. Would be great from 3 tier app with basic data structure.

Ghost doc… well it just helps with documenting your code. Its very simple but anything that helps with the mundane is a good thing in my book.

Sandcastle – Documentation

Posted in Documentation, Sandcastle by

We are coming to the end of the project here at work so needless to say all the documentation has to be handed over, including the API for the code base.
As we using .Net 3.0 Ndoc cant be used so its replacement sandcastle was our obvious option. Sandcastle being still a CTP is pretty clumsy to use, so here is some tips to get you going.

firstly check out the Gui or batch tools out there, some of them are pretty good. Check the codeplex stuff and SandcastleGUI.
Unfortunately this (specifically SandcastleGUI) wouldnt work for me as it tries to find DLLs that may be referenced even if not used (this may point to redundant ref in our code). as time was not on my side i decide to just run with the default console implementation.

…Anyway some tips.
Put all your Dll’s in one directory. Even if this means copying them all into a holder directory for the means of the documentation exercise. This includes anything that the dll’s may reference. Normally this is the case anyway, however with distributed systems, and gacs, and what not, it isnt always the case.

Assuming you install sandcastle in “C:\Program Files\Sandcastle” the below script will create your help file.

“C:\Program Files\Sandcastle\ProductionTools\MRefBuilder.exe” alpha.dll beta.dll gamma.dll /out:reflection.org

“C:\Program Files\Sandcastle\ProductionTools\XslTransform.exe” /xsl:”C:\Program Files\Sandcastle\ProductionTransforms\ApplyVSDocModel.xsl” reflection.org /xsl:”C:\Program Files\Sandcastle\ProductionTransforms\AddFriendlyFilenames.xsl” /out:reflection.xml

“C:\Program Files\Sandcastle\ProductionTools\XslTransform.exe” /xsl:”C:\Program Files\Sandcastle\ProductionTransforms\ReflectionToManifest.xsl” reflection.xml /out:manifest.xml

call “C:\Program Files\Sandcastle\Presentation\vs2005\copyOutput.bat”

“C:\Program Files\Sandcastle\ProductionTools\BuildAssembler.exe” /config:”C:\Program Files\Sandcastle\Presentation\vs2005\Configuration\sandcastle.config” manifest.xml

“C:\Program Files\Sandcastle\ProductionTools\XslTransform.exe” /xsl:”C:\Program Files\Sandcastle\ProductionTransforms\ReflectionToChmProject.xsl” reflection.xml /out:Output\test.hhp

“C:\Program Files\Sandcastle\ProductionTools\XslTransform.exe” /xsl:”C:\Program Files\Sandcastle\ProductionTransforms\createvstoc.xsl” reflection.xml /out:toc.xml

“C:\Program Files\Sandcastle\ProductionTools\XslTransform.exe” /xsl:”C:\Program Files\Sandcastle\ProductionTransforms\TocToChmContents.xsl” toc.xml /out:Output\test.hhc

“C:\Program Files\Sandcastle\ProductionTools\XslTransform.exe” /xsl:”C:\Program Files\Sandcastle\ProductionTransforms\ReflectionToChmIndex.xsl” reflection.xml /out:Output\test.hhk

“C:\Program Files\HTML Help Workshop\hhc.exe” output\test.hhp
pause

The only change you would then need for this script is to put the names of the DLL’s you actually want to document (ie replace alpha.dll beta.dll gamma.dll with your dll(s))… you may want to do this before running the batch file 😉

Copy and paste the script below into a text file make the dll name change on the first line sand save it as a batch file eg “documentation.bat”. Save it in the same folder as your dll’s and run it (click it).

This will give you an ultra generic help file, ala visual studio 2005 and all the rubbish .net 2.0 help files when it first came out.
I personally played with the xsl file to add in images etc to customise it a bit. i’m sure there are better ways to do it but i’m not spending any more time on some thing that i doubt anyone will ever read.
If you want them all spruced up, you probably want to check out the tools mentioned above.

EDIT: Sorry I fogot to mention that I dont name all of my XML Comment files “comments.xml”!
I usually name them the same as my dll’s with an xml extension eg alpha.dll has the comment file alpha.xml. This means I had to make a change in the sandcastle config file (“C:\Program Files\Sandcastle\Presentation\vs2005\configuration\sandcastle.config” in my case) line 63 from

to

to allow for all of the xml files to be a part of the help (which is what you really want now isn’t it!).
Just make sure there are only comment XML files (ie no other data xml files) in the directory or i guess it could go pear shaped. Alternatively perhaps name them *.dll.xml and use that as the data file filter.
EDIT 2:
To change the lines at the top & bottom of the main pages
[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]
&

Send comments about this topic to Microsoft.

Edit the shared_content.xml file found below.
C:\Program Files\Sandcastle\Presentation\*\Content\shared_content.xml