Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I'm a Web Developer about to unlock the "First Class Library Published" achievement in my career and I'm sweating bullets (literally - I was up all night stressing out). I'd love to tap the experience of the community to see if anyone has any suggestions or recommendations for making sure this goes as smoothly as possible. Are there any specifics or gotchas I need to be aware of? Anything special about the build process that can come back to bite me?

Here's where I'm at:

  • Library is unit tested and has approx 97% code coverage
  • API is well documented and xml docs for intellisense support have been created
  • I've ensured that public/private class accessors are accurate and correct. The same goes for all getters/setters
  • Error handling isn't as graceful as I'd like it to be, but I'm up against a deadline and have accepted that its an "as good as its going to be" for now
  • No friendly logging. Debug.Writeline was used extensively...I've learned recently that this is a reflection of my inexperience :(

Your advice is greatly appreciated!

The library will be used to generate reports. Standard hat -- connects to readonly database, performs calcs, formats and outputs data to response stream.


I was tapped as a fringe resource to fill in for one of the programmers that quit, and this task was given to me as a "cut your teeth" project. The class library is going to be released for other programmers in the company to use while they write production code.

share|improve this question
1  
Need details, release how? Release for sale? Release open-source for sharing? Releasing to a client per a contract you're on? Releasing to the rest of your development organization as part of a project for your full-time employer? Releasing as v1.0 of a new product to client availability for your full-time employer? –  Jimmy Hoffa Jan 8 '13 at 18:29
    
@JimmyHoffa: added answers to your questions. Thanks for taking hte time! –  ajax81 Jan 8 '13 at 19:19
1  
Pretend you are a user of the library with no knowledge of how it works. Use it to build something. Change/remove/add things based on the experience. Then release it to real users and get their feedback. –  mike30 Jan 8 '13 at 19:31
    
Maybe use Sandcastle or other doc-generating library to have offline(ish) reference material? –  Jesse C. Slicer Jan 8 '13 at 19:44
7  
Relax. Having even one single unit test and one single line of API documentation already elevates this release above ~95% of code "released for other programmers in the company to use", in my experience. –  Carson63000 Jan 8 '13 at 20:09
show 1 more comment

2 Answers 2

up vote 6 down vote accepted

Lock-in the API

The art of effectively building an API is as much about managing expectations as it is about structure.

When I say API I'm specifically referring to how the public/internal classes/methods are named and what their access level is (ie private/public/internal).

If you're worried that the code may not be completely ready for prime-time you could always initially publish it as beta.

Releases:

  • Beta (ie pre 1.0)

    • may contain multiple API breaking changes
    • may lack backwards-compatibility changes between versions
    • may have a lack of polish
  • Official (1.0+)

    • API is locked in until the next major release
    • any changes introduced should guarantee backward compatibility
  • Minor (ex 1.1)

    • contain bug-fixes and-or feature implementations
    • may add-to but not take away from the defined API

If you think the API needs to be battle-hardened some then release it for a while as beta. That signals that it is available for use but shouldn't be used for production and/or mission-critical code.

Many people treat numbered versioning schemes like hogwash but when they're used effectively they can be used to provide some wiggle room until you get the structure sorted out.

Your assumptions about how it will be used are wrong

No matter how well something is designed, people will find a way to abuse or create an alternate use.

One way to handle this is to lock down as much of the implementation as possible using accessors (ie private/public/internal) but no amount of design or engineering will give you as much insight as releasing the code to the users.

It really doesn't matter how 'perfect' you think your code can become, your users will prove that it's not.

I would argue that this is the primary reason why it's always better to use an existing codebase rather than do a full rewrite. At best a complete rewrite will trim the bloat but there's a high likelihood that the new codebase will contain as many (and possibly more) bugs as the original codebase.

In your case you're battle-hardening from scratch so you might as well get started.


It sounds like you have the rest of your bases covered. API documentation is vital and tests will be good for ensuring stability when changes are made in the future.

Implementing a consistent logging scheme will be important before the code is released for production because you'll need a way to globally enable/disable/filter the logs. BTW, in most cases logging only really involves importing a library and changing the output calls from Debug.WriteLine() to something like Logging.Debug(), Logging.Info(), Logging.Error(). The logger itself just provides a standard implementation for configuration, filtering, and a wider range of output schemes (ex files, console, etc).

Other than that, I'd look to get the code out and being used. Even if only by a small number of users to start.

share|improve this answer
1  
+1 Re: logging - I highly recommend TraceSource. It introduces no external dependencies since it is part of the core .NET libraries and it allows users to attach listeners and configure tracing both through code and through app.config files. –  Dan Lyons Jan 30 '13 at 18:32
add comment

These are two things that I find are key to releasing software:

  • Know exactly what you have released
  • Manage expectations

You want to be able to go back and bug fix what you have released and you want people to understand what problem your code will solve.

Knowing what you have released

Make sure you have it correctly versioned and signed (if approriate). Use your source control to tag\label the code associated with the officially released version. This will help you identify bugs easier as you can go back to exactly the source code you released. It will also help down the line when you might have a few different released versions.

Try to make the latest version easy to get hold of and update. Whether that's an installer, or simply putting it on a common share is dependent on who\when\how often you will be shipping.

Make sure that you have someone review your final release, including the documentation. It's very easy to become nervous or excited about releasing software and miss something.

Managing expectations

Document the limitations and make them reasonably obvious to the developers. It is good that you have found them. People are often more understanding if they know the limitations with your software, especially if you have a plan to fix them.

Document how you would like feedback, good or bad. As it is an internal project, if everyone has access to a common bug tracking system, ask them to file bugs against the appropriate project.

In the future, avoid changing the API if possible, this is the one thing that has the potential to annoy your customers. Remember that exceptions are part of the API too, even though in C# they're not a part of the method documentation. It may be possible to improve the exceptions being thrown at a later date, but you will need to talk to the end users and see what impact it will have.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.