Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I have always liked the documentation on Java APIs, generally speaking, but I know some people consider them lacking. So I'm wondering, what do you consider a good example of API documentation?
Please, include a link or an actual example in any answer. I want to have references that I (and others, of course) can use to improve our own documents.
A good documentation MUST have:
datatypes specs - often more essential than actual functions. Do NOT treat this lightly.
function specs (this is obvious). Including What given function does, why it does it (if not obvious), and caveats if any.
an introduction document that binds the whole into a logical entity, explaining the intentions, correct usage patterns and ideas beyond the scope of actual API code. Normally you are given 50 different functions and you don't know which must be used, which shouldn't be used outside of specific cases, which are recommended to more obscure alternatives and why must they be used that way.
examples. Sometimes they are more important than all the rest
I know how to draw an arbitrary shape of arbitrary color in GTK+. I still have no clue why a change of drawing color requires three quite long lines of very obscure, quite unintuitive lines of code. Remembering SVGAlib's setcolorRGB(r,g,b); draw(x1,y1,x2,y2); I find it really hard to comprehend what possessed the authors of GTK+ to complicate things so much. Maybe if they explained the underlying concepts instead of just documenting functions that use them, I'd understand...
Another example: yesterday I got an answer that allowed me to understand SQLite. I understood a function extracting data from a column returns signed long long. I understood the integer columns could be 1,2,4,6 and 8 bytes long. I understood I can define a column as "UNSIGNED INT8", or "TINYINT". I didn't quite get what "affinity" meant, I just knew both had "INTEGER" affinity. I spent hours seeking whether timestamps should be UNSIGNED INTEGER or INT8, whether INT8 is 8-digits or 8-bytes, and what is the name of that esoteric 6-byte int?
What I missed was that "UNSIGNED INT8", "TINYINT" and the like are all a syntactic sugar synonyms for "INTEGER" type (which is always signed long long), and the lengths given are for internal disk storage only, are adjusted automatically and transparently to fit any value on least number of bits and are totally invisible and inaccessible from the API side.
Actually the iPhone (really Mac Cocoa/framework) documentation has gotten pretty good. The features I like are:
Very easy jump to docs from the API.
Well formatted and the code snippets
you would want to copy and paste
(like method signatures) stand out.
Links to projects with sample code
right from the docs.
Automated document refresh mechanism,
but by default docs are all local to
start (so you can live with a flaky
internet connection).
Easy way to switch between variants
of documentation (to see different
versions of the OS), and also select
which sets of documentation to run
searches against.
An overview section explains what the
class is for, followed by a section
breaking out methods grouped by
purpose (methods to create and
object, methods to query for data,
methods to work with type
conversions, etc), followed by the
detailed method explanations.
I also personally really liked Javadoc and the Java system documentation (I used that for many years), I found a benefit there was it was a little easier to make your own custom docs for your own classes that flowed well with the system docs. XCode lets you also use Doxygen to generate documentation for your own classes, but it would take a but more work to format it as well as the system class docs, in part because the system framework documents have more formatting applied.
A good API will have the following characteristics:
Easy to learn
Easy to use, even without documentation
Hard to misuse
Easy to read and maintain code that uses it
Sufficiently powerful to satisfy requirements
Easy to extend
Appropriate to audience
The most common mistake I see in API design is when developers feel auto-generated XML commenting is sufficient, and then precede to auto-generate their API based off of the XML comments. Here's what I'm talking about:
///<summary>
/// Performs ObscureFunction to ObscureClass using ObscureArgument
///</summary>
void ObscureClass.ObscureFunction(ObscureArgument) { ... }
API's like the one above are only counter-productive and frustrate the developer using the API. Good API documentation should give developers hints as to how to use API and give them insight into certain facets of the API they otherwise would not notice.
I personally believe a perfect example of good documentation is PHP's documentation:
For an example:
http://www.php.net/manual/en/function.fopen.php
I think effective documentation includes:
Parameter listing
(Useful) description of the parameter
If they parameters are a string, list
out and EXPLAIN every possible
possible parameter
Return values on both successful
execution and non-successful
execution
Any exceptions/errors it can raise
Examples (THE MOST IMPORTANT imo)
Optionally:
Changelog
Notes/Examples from other users
Whenever I look up something in the PHP documentation I almost know exactly how to use it without having to scour the internet to find "better" examples. Usually the only time which I need to search the internet is when I need to find how to use a set of functions for a specific purpose. Otherwise, I think the PHP documentation is the greatest example of excellent documentation.
What is think is an example of a alright documentation is Python's:
http://docs.python.org/py3k/library/array.html
It lists out the methods but it doesn't do a good job of actually explaining in depth what it is, and how to use it. Especially when you compare it to the PHP docs.
Here is some really bad documentation: Databinder Dispatch. Dispatch is a Scala library for HTTP that abstracts away the (Java) Apache Commons HTTP library.
It uses a lot of functional-syntax magic which not everyone is going to be very clear on, but provides no clear explanation of it, nor the design decisions behind it. The Scaladocs aren't useful because it isn't a traditional Java-style library. To really understand what is going on, you basically have to read the source code and you have to read a load of blog posts with examples.
The documentation succeeds in making me feel stupid and inferior and it certainly doesn't succeed in helping me do what I need to do. The flipside is most of the documentation I see in the Ruby community - both RDoc and in FAQs/websites/etc. Don't just do the Javadoc - you need to provide more comprehensive documentation.
Answer the question: "how do I do X with Y?" You may know the answer. I don't.
My main criteria is - tell me everything I need to know and everything I'll ever want to know.
QT has pretty decent docs:
http://doc.qt.digia.com/4.5/index.html
Win32 MSDN is also pretty good although it didn't age well.
The java docs are horrible to me. They constantly tell me everything I don't want to know and nothing of what I do want to know. The .NET docs has a similar tendency although the problem there is mostly the extreme wordyness, overflow of so much superfluous details and so much god damn pages. Why can't I see both the summary and the methods of a class in the same page?
I like Twitter's documentation. To me a good API is up to date, easy to read and contains examples.
I think that a good API document needs to clearly explain:
What problem this API solves
When you should use it
When you shouldn't use it
Actual code showing "best practice" usage of the API
Not quite API documentation but nevertheless quite useful is the Oracle database documentation, e.g. for the SELECT statement. I like the inclusion of diagrams which helps to clarify the usage for example.
Just a few thoughts...
Examples - win32 API documentation is better than iPhone's because of:
(short) code examples
I vote for any API doc with small and make-sense examples
Don't ever never show "Form1", "asdf", "testing users" in screen shots or sample codes
good API is solving real world problems and there should be some meaningful examples
Don't auto-gen doc
documentation should not be done during writing code (or by the same guy)
doc is for a stranger, whom the programmers usually don't care of
Avoid ___V2 version of API
but it's not a doc issue
Basically, tell the story of the class at the class level. Why is this here? What should it do? What should be in here? Who wrote it?
Tell the story of methods at the method level. What does this do? No matter how accurate your methods names are, 20-30 characters just won't always cut it for descriptiveness.
#author:
Who wrote this? Who's proud of it? Who should be ashamed of their work?
Interface level documentation tells me:
what should this do?
what will it return?
Implementation level documentation tells me:
how does it do it? what kind of algorithm? what sort of system load?
what conditions might cause a problem? will null input cause an issue? are negative numbers okay?
Class level documentation tells me:
what goes here? what kind of methods should I expect to find?
what does this class represent?
#Deprecated tells me:
why is this planned for removal?
when is it expected to be removed?
what is the suggested replacement?
If something is final:
why didn't you want me to extend this?
If something is static:
remind me in the class level doc, at least implicitly.
In general: you're writing these for the next developer to use if and when you hit the lottery. You don't want to feel guilty about quitting and buying a yacht, so pay a bit of attention to clarity, and don't assume you're writing for yourself.
As the side benefit, when someone asks you to work with the same code two years from now and you've forgotten all about it, you're going to benefit massively from good in-code documentation.
First point for a great API-documentation is a good naming of the API itself. The names of methods and parameters should be say all. If the language in question is statically typed, use enums instead of String- or int-constants as parameters, to select between a limited set of choices. Which options are possible can now be seen in the type of the parameter.
The 'soft-part' of documentation (text, not code) should cover border-cases (what happens if I give null as parameter) and the documentation of the class should contain a usage-example.
Good documentation should have at least the following:
When an argument has additional limitations beyond its type, they need to be fully specified.
Description of the [required] state of an object before calling the method.
Description of the state of an object after calling the method.
Full description of error information provided by the method (return values, possible exceptions). Simply naming them is unacceptable.
Good example: Throws ArgumentOutOfRangeException if index is less than 0 -or- index is greater than or equal to Count.
Bad example: Returns 0 for success or one of the following E_INVALIDARG, etc... (without specifying what makes an argument invalid). This is standard "FU developer" approach taken in the PS3 SDK.
In addition, the following are useful:
Description of the state of an object if an exception is thrown by the method.
Best practices regarding classes and groups of classes (say for exceptions in .NET) in the API.
Example usage.
Based on this:
An example of great documentation is the MSDN library.
To be fair, the online version of this does suffer from difficulty of navigation in cases.
An example of terrible documentation is the PS3 SDK. Learning an API requires extensive testing of method arguments for guessing what may or may not be the actual requirements and behavior of any given method.
IMO examples are the best documentation.
I really like the Qt4 Documentation, it first confronts you only with the essential information you need to get things working, and if you want to dig deeper, it reveals all the gory details in subsections.
What I really love, is the fact that they built the whole documentation into Qt Creator, which provides context sensitive help and short examples whenever you need them.
One thing I've always wanted to see in documentation: A "rationale" paragraph for each function or class. Why is this function there? What was it built for? What does it provide that cannot be achieved in any other way? If the answer is "nothing" (and surprisingly frequently it is), what is it a shorthand for, and why is that thing important enough to have its own function?
This paragraph should be easy to write - if it's not, it's probably a sign of a dubious interface.
I have recently come across this documentation (Lift JSON's library), which seems to be a good example of what many people have asked for: nice overview, good example, use cases, intent, etc.
i like my documentation to have a brief overview at the top, with fully featured examples below, and discussions under these! I'm surprised that few include simple function arguments with their required variable types and default values, especially in php!
I'm afraid i can't really give an example because i havent trawled through to find which ones my favourite, however i know this probably doesn't count because its unofficial but Kohana 3.0's Unofficial Wiki By Kerkness is just brilliant! and the Kohana 2.34 documentation is pretty well laid out too, well at least for me. What do you guys think?
Most people have listed the points making up good API documentation, so I am not going to repeat those (data type specs, examples, etc.). I'm just going to provide an example which I think illustrates how it should be done:
Unity Application Block (Go to the Download section for the CHM)
All the people involved in this project have done a great job of documenting it and how it should be used. Apart from the API reference and detailed method description, there are a lot of articles and samples which give you the big picture, the why and how. The projects with such good documentation are rare, at least the ones I use and know about.
The only criteria for documentation quality is that it speeds up development. If you need to know how something works, you go and read docs. One doc is better than another if you've understood everything from first doc faster than from from second.
Any other qualities are subjective. Styles, cross-references, descriptions… I know people who likes to read books. Book-styled doc (with contents/index/etc.) will be good for him. Another my friend likes to doc everything inside code. When he downloads new library, he gets sources and "reads" them instead of docs.
I, personally, like JavaDocs. Like Apple dev docs with the exception of lower-level parts, for example, Obj-C runtime (reference part) is described awfully. Several website APIs have docs I like also.
Don't like MSDN (it's good in general but there are too many variants of the same document, I get lost often).
Documentation is only a part of the big picture, API design. And one could argue the latter is much more important than just the naming. Think of meaningful non-duplicating method names, etc.
I would definitely recommend watching Josh Bloch's presentation about this:
http://www.infoq.com/presentations/effective-api-design OR http://www.youtube.com/watch?v=aAb7hSCtvGw
This covers not only what you're looking for but much more.
Lots of practical, real-world examples are a must. The recent rewrite of jQuery's API documentation is a good example, as well as Django's legendary docs.
The best documentation I've found is Python. You can use sphinx to generate the source documentation into HTML, LaTeX and others, and also generate docs from source files; the API doc you are looking for.
API docs is not only the quality of the final documentation, but also how easy is for the developers and/or technical writers to actually write it, so pick a tool that make the work easier.
Most things about good documentation have already been mentioned, but I think there is one aspect about the JavaDoc way of API documentation that is lacking: making it easy to distinguish between the usage scenarios of all the different classes and interfaces, especially distinguishing between classes that should be used by a library client and those that should not.
Often, JavaDoc is pretty much all you get and usually there is no package documentation page. One is then confronted with a list of hundreds or even more of classes: where and how to start? What are typical ways of using the library?
It would be good if there were conventions of how to make it easy to provide this information as part of JavaDoc. Then the generated API documentation could allow for different views for different groups of people -- at a minimum two groups: those who implement the library and those who use it.
I find Google APIs a beautiful example of Good documentation API.
They have:
Bird's eyes view of the entire APIs structure
Overviews of the main features of the single API
Nice and colored examples for a quick feedback
Detailed references
A blog that keep you updated
A google groups that documents problems and solutions
Videos
FAQ
Articles
Presentations
Code Playground
A search engine to crawl inside a pile of documentation
That's it!
When I play with google APIs documentation site, I feel at home.
Go to the Doxygen site and look at the examples of the HTML that it generates. Those are good:
http://www.doxygen.nl/results.html
I asked this question about Microsoft .NET Libraries and the complexity of its source code. From what I'm reading, writing general purpose libraries and writing applications can be two different things. When writing libraries, you have to think about the client who could literally be everyone (supposing I release the library for use in the general public).
What kind of practices or theories or techniques are useful when learning to write libraries? Where do you learn to write code like the one in the .NET library? This looks like a "black art" which I don't know too much about.
That's a pretty subjective question, but here's on objective answer. The Framework Design Guidelines book (be sure to get the 2nd edition) is a very good book about how to write effective class libraries. The content is very good and the often dissenting annotations are thought-provoking. Every shop should have a copy of this book available.
You definitely need to watch Josh Bloch in his presentation How to Design a Good API & Why it Matters (1h 9m long). He is a Java guru but library design and object orientation are universal.
One piece of advice often ignored by library authors is to internalize costs. If something is hard to do, the library should do it. Too often I've seen the authors of a library push something hard onto the consumers of the API rather than solving it themselves. Instead, look for the hardest things and make sure the library does them or at least makes them very easy.
I will be paraphrasing from Effective C++ by Scott Meyers, which I have found to be the best advice I got:
Adhere to the principle of least astonishment: strive to provide classes whose operators and functions have a natural syntax and an intuitive semantics. Preserve consistency with the behavior of the built-in types: when in doubt, do as the ints do.
Recognize that anything somebody can do, they will do. They'll throw exceptions, they'll assign objects to themselves, they'll use objects before giving them values, they'll give objects values and never use them, they'll give them huge values, they'll give them tiny values, they'll give them null values. In general, if it will compile, somebody will do it. As a result, make your classes easy to use correctly and hard to use incorrectly. Accept that clients will make mistakes, and design your classes so you can prevent, detect, or correct such errors.
Strive for portable code. It's not much harder to write portable programs than to write unportable ones, and only rarely will the difference in performance be significant enough to justify unportable constructs.
Even programs designed for custom hardware often end up being ported, because stock hardware generally achieves an equivalent level of performance within a few years. Writing portable code allows you to switch platforms easily, to enlarge your client base, and to brag about supporting open systems. It also makes it easier to recover if you bet wrong in the operating system sweepstakes.
Design your code so that when changes are necessary, the impact is localized. Encapsulate as much as you can; make implementation details private.
Edit: I just noticed I very nearly duplicated what cherouvim had posted; sorry about that! But turns out we're linking to different speeches by Bloch, even if the subject is exactly the same. (cherouvim linked to a December 2005 talk, I to January 2007 one.) Well, I'll leave this answer here — you're probably best off by watching both and seeing how his message and way of presenting it has evolved :)
FWIW, I'd like to point to this Google Tech Talk by Joshua Bloch, who is a greatly respected guy in the Java world, and someone who has given speeches and written extensively on API design. (Oh, and designed some exceptionally good general purpose libraries, like the Java Collections Framework!)
Joshua Bloch, Google Tech Talks, January 24, 2007:
"How To Design A Good API and Why it
Matters" (the video is about 1 hour long)
You can also read many of the same ideas in his article Bumper-Sticker API Design (but I still recommend watching the presentation!)
(Seeing you come from the .NET side, I hope you don't let his Java background get in the way too much :-) This really is not Java-specific for the most part.)
Edit: Here's another 1½ minute bit of wisdom by Josh Bloch on why writing libraries is hard, and why it's still worth putting effort in it (economies of scale) — in a response to a question wondering, basically, "how hard can it be". (Part of a presentation about the Google Collections library, which is also totally worth watching, but more Java-centric.)
Krzysztof Cwalina's blog is a good starting place. His book, Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, is probably the definitive work for .NET library design best practices.
http://blogs.msdn.com/kcwalina/
The number one rule is to treat API design just like UI design: gather information about how your users really use your UI/API, what they find helpful and what gets in their way. Use that information to improve the design. Start with users who can put up with API churn and gradually stabilize the API as it matures.
I wrote a few notes about what I've learned about API design here: http://www.natpryce.com/articles/000732.html
I'd start looking more into design patterns. You'll probably not going to find much use for some of them, but as you get deeper into your library design the patterns will become more applicable. I'd also pick up a copy of NDepend - a great code measuring utility which may help you decouple things better. You can use .NET libraries as an example, but, personally, i don't find them to be great design examples mostly due to their complexities. Also, start looking at some open source projects to see how they're layered and structured.
A couple of separate points:
The .NET Framework isn't a class library. It's a Framework. It's a set of types meant to not only provide functionality, but to be extended by your own code. For instance, it does provide you with the Stream abstract class, and with concrete implementations like the NetworkStream class, but it also provides you the WebRequest class and the means to extend it, so that WebRequest.Create("myschema://host/more") can produce an instance of your own class deriving from WebRequest, which can have its own GetResponse method returning its own class derived from WebResponse, such that calling GetResponseStream will return your own class derived from Stream!
And your callers will not need to know this is going on behind the scenes!
A separate point is that for most developers, creating a reusable library is not, and should not be the goal. The goal should be to write the code necessary to meet requirements. In the process, reusable code may be found. In that case, it should be refactored out into a separate library, where it can be reused in the future.
I go further than that (when permitted). I will usually wait until I find two pieces of code that actually do the same thing, or which overlap. Presumably both pieces of code have passed all their unit tests. I will then factor out the common code into a separate class library and run all the unit tests again. Assuming that they still pass, I've begun the creation of some reusable code that works (since the unit tests still pass).
This is in contrast to a lesson I learned in school, when the result of an entire project was a beautiful reusable library - with no code to reuse it.
(Of course, I'm sure it would have worked if any code had used it...)
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I am converting an open source Java library to C#, which has a number of methods and classes tagged as deprecated. This project is an opportunity to start with a clean slate, so I plan to remove them entirely. However, being new to working on larger projects, I am nervous that the situation will arise again. Since much of agile development revolves around making something work now and refactoring later if needed, it seems like deprecation of APIs must be a common problem. Are there preventative measures I can take to avoid/minimize API deprecation, even if I am not entirely sure of the future direction of a project?
I'm not sure there is much you can do. Requirements change, and if you absolutely have to make sure that clients of the API are not broken by newer API version, you'll have rely on simply deprecating code until you think that no-one is using the deprecated code.
Placing [Obsolete] attributes on code causes the compiler to create warnings if there are any references to the obsolete methods. This way clients of the API, if they are diligent about fixing their compiler warnings, can gradually move to the new methods without having everything break with the new version.
Its useful if you use the ObsoleteAttribute's override which takes a string:
[Obsolete("Foo is deprecated. Use Bar instead for munging widgets.")]
<frivolous>
Perhaps you could create a TimeBombAttribute:
[TimeBomb(new DateTime(2010,1,1), "Foo will blow up! Better use Bar, or else."]
In your code, reflect for methods with the timebomb attribute and throw KaboomException if they are called after the specified date. That'll make sure that after 1st January 2010 no-one is using the obsolete methods, and you can clean up your API nicely. :)
</frivolous>
As Matt says, the Obsolete attribute is your friend... but whenever you apply it, provide details of how to change calling code. That way you've got a lot better chance of people actually changing. You might also want to consider specifying which version you anticipate removing the method in (probably the next major release).
Of course, you should be diligent in making sure you don't call the obsolete code - particularly in sample code.
Since much of agile development revolves around making something work now and refactoring later if needed
That's not agile. It's cowboy coding disguised under the label of agile.
The ideal is that whatever you complete, is complete, according to whatever Definition of Done you have. Usually the DoD states something along the lines of "feature impelmented, tested and related code refactored". Of course, if you are working on a throwaway prototype, you can have a more relaxed DoD.
API modifications are a difficult beast. If they are only project-internal APIs you are modifying, the best way to go is to refactor early. If you need to change the internal API, just go ahead and change all API clients at the same time. This way the refactoring debt does not grow very large and you don't have to use deprecation.
For published APIs you probably have some source and binary compatibility guarantees you have to maintain, at least until the next major release or so. Marking the old APIs deprecated works while maintaining compatibility. As with internal APIs, you should fix your internal code as soon as possible to not use the deprecated APIs.
Matt's answer is solid advice. I just wanted to mention that intially you probably want to use something along the lines of:
[Obsolete("Please use ... instead ", false)]
Once you have the code ported, change the false to true and the compiler will then treat all the calls to the method as an error.
Watch Josh Bloch's "How to Design a Good API and Why It Matters"
Most important w/r/t deprecation is knowing that "when in doubt, leave it out." Watch the video for clarification, but it has to do with having to support what you provide forever. If you are realistically expecting that API to be reused, you're effectively setting your decisions in stone.
I think API design is a much trickier thing to do in an Agile fashion because you're expecting it to be reused probably in many different ways. You have to worry about breaking others that are dependent on you, and so while it can be done, it's tough to have the right design emerge without getting a quick turnaround from other teams. Of course deprecation is going to help here, but I think YAGNI is a lot better design heuristic when it comes to APIs.
I think deprecation of code is an inevitable byproduct of Agile processes like continuous refactoring and incremental development. So if you end up with deprecated code as you work on your project, that's not necessarily a bad thing--just a fact of life. Of course, you will probably find that, rather than deprecating code, you end up keeping a lot of code but refactoring it into different methods, classes, and so on.
So, bottom line: I wouldn't worry about deprecating code during Agile development. If it served its purpose for a while, you're doing the right thing.
The rule of thumb for API design is to focus on what it does, rather than how it does it. Once you know the end goal, figure out the absolute minimum input you need and use that. Avoid passing your own objects as parameters, pass only data.
Seperate configuration from execution. For exmaple, maybe you have an image encoder/decoder.
Instead of making a call like:
Encoder.Encode( bytes, width, height, compression_type, compression_ratio, palette, etc etc);
Make it
Encoder.setCompressionType(compression_type);
Encoder.setCompressionType(compression_ratio);
etc,etc
Encoder.Encode(bytes, width, height);
That way adding or removing settings is much less likely to break existing implementations.
For deprecation, there's basically 3 types of APIs: internal, external, and public.
Internal is when its only your team working on the code. Deprecating these APIs isn't a big deal. Your team is the only one using it, so they aren't around long, there's pressure to change them, people aren't afraid to change them, and people know how to change them.
External is when its the same code base, but different teams are using it. This might be some common libraries in a large company, or a popular open source library. The point is, people can choose the version of code they compile with. The ease of deprecating an API depends on the size of the organization and how well they communicate. IMO, its the deprecator's job to update old code, rather than mark it deprecated and let warnings fly throughout the code base. Why the deprecator instead of the deprecatee? Because the depcarator is in the know; they know what changed and why.
Those two cases are pretty easy. So long as there is backwards compatibility, you can generally do whatever you'd like, update the clients yourself, or convince the maintainers to do it.
Then there are public api's. These are basically external API's that the clients don't have much control over, such as a web API. These are incredibly hard to update or deprecate. Most won't notice its broken, won't have someone to fix it, won't get notifications that its changing, and will only fix it once its broken (after they've yelled at you for breaking it, over course).
I've had to do the above a few times, and it is such a chore. I think the best you can do is purposefully break it early, wait a bit, and then restore it. You send out the usual warnings and deprecations first, of course, but - trust me - nothing will happen until something breaks.
An idea I've yet to try is to let people register simple apps that run small tests. When you want to do an API update, you run the external tests and contact the affected people.
Another approach to be popular is to have clients depend on (web) services. There are constructs out there that allow you to version your services and allow clients to perform lookups. This adds a lot more moving parts and complexity into the equation, but can be helpful if you are looking at turning over a lot of versions, and having to support multiple versions in production.
This article does a good job of explaining the problem and an approach.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 years ago.
Improve this question
One thing I've always found frustrating is when a library I use is no longer maintained. Even looking at update history and community beforehand, I've run into the situation where I check back later to find that the version I'm using is the last version.
Generally this goes unnoticed until a few months have passed, or some bug/limitation has been found. I run into this fairly often when coding in Python, because my desire to upgrade to a new version of the interpreter can easily introduce problems in libraries that worked fine before. My question is: what is the best response to this situation?
Do you become the maintainer of the old library? Even if you're only fixing the bugs you care about, this is still a lot of work. Especially if the library is large, complex, and has less-than-well-documented code (the case more often than not).
Do you switch to a different library (if there is one)? This is also a significant undertaking, with the potential to introduce new bugs, especially if the only alternatives approach the problem from a different angle. This can be true even if you had the foresight to write an abstraction layer for the old library's functionality.
Do you roll your own? It probably ends up as less code than the old library, since you only write the parts you care about. It's therefore easier to maintain in the future. But now you've wasted days/weeks/months to produce something that is probably less functional, and is guaranteed to introduce tons of new bugs.
I realize the answer depends on the specific case: the size of the library, whether source is available, how maintainable it is, how much of it your code uses, how deeply your code relies on it, etc. I'm looking for answers across a range of cases. What are your experiences with this problem?
Well, you've found one argument to lessen the number of external dependencies...
I've come across this in several Java projects I've audited; it seems people have a tendency to drop in a Jar found somewhere on the Web for the tiniest amount of reuse possible from it. The result is a mess of dependencies that ends up undermining the code base. I prefer to use external components sparingly.
It's probably most useful to ask what you can do before. Make a point of evaluating the future lifetime of an external component before you start using it. Do some research on how large its developer community and its user community are. Also, prefer to use a component that has one or two "lesser" alternatives which you could also use.
If there's something you're tempted to use, but it has only one or two people working on it and isn't used much beyond their own project, then you should probably roll your own - or join forces with the maintainers of the component.
I think your really answer is in how do you select third party libraries to include in your code.
If you happen to like constantly upgrading your code to the latest version of the language then by default you can only use libraries that have active communities behind them
In fact I would go as far as saying that the only time that you want to use a third party open source library is when the community behind it is large (say at least 40+ users) and it has undergone a few releases.
For a commercial library the same thing applies how long is the company going to be around and how many other clients use it.
If you can't find a library in this position then ensure that you abstract the third party library out of your code so replacement isn't hard in the future.
When the Java EE framework my employer chose went belly up, we went out and found a newer, better one. Fortunately Spring was available.
We prefer to roll our own for that very reason. We end up with full control over it, full knowledge of how it works, and we can change it any way we want. When our ass is on the line when the blame game is played, we prefer to reduce the risk and do it ourselves.
We had a situation once where we did use an external library, and it got rewritten and repurposed by the author and no longer did what we expected. We rolled over that, wrote our own version, and continued safely.
The bottom line is safety, and minimization of risk.
If the source is available, the licence is open and the library does the job really well, you have the option to fork the library. By doing this, you can also add new features to it. If the library has lots of things to fix and the code is a mess, it is better to find something else to work with.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
What would you suggest for the following scenario:
A dozen of developers need to build and design a complex system. This design needs to be documented for future developers and the design decisions must be noted. These reports need to be made about every two months. My question is how this project should be documented.
I see two possibilities. Each developer writes about the things they helped design and integrate and then one person combines each of these documents together. The final document will probably be incoherent or redundant at times since the person tasked of assembling everything won't have much time to adjust every part.
Assume that the documentation parts from each developer arrive just a few days before deadline. A collaborative system (i.e. wiki) wouldn’t work properly since there wouldn’t be anything to read until a few days before deadline.
Or should a few people (2-3) be tasked with writing the documentation while the rest of the team works on actually developing the system? The developers would need a way to transfer their design choices and conclusions to the technical writers. How could this be done efficiently?
We approach this from 2 sides, using a RUP style approach. In the first case, you'll have a domain expert who is responsible for roughing out the design of what you're going to deliver - with developers chipping in as necessary. In the second case, we use a technical author - they document the application, so they should have a good idea of how it hangs together, and you involve them right through the design and development process. In this case, they can help to polish the design, and to make sure that it matches what they thought was being developed.
We use confluence (atlassian's wiki-like-thing) and document all kinds of different "things". The developers do it continiously, and we push each other for docs - we let peer pressure decide what is necessary. Whenever someone new comes along he/she is tasked with reading through everything and to find out what still is correct. The incorrect stuff is either deleted or updated as a consequence of this. We're happy when we can delete stuff ;)
The nice thing about this process is that the relevant stuff stays and the irrelevant stuff is deleted. We always "got away" from the more formalized demands by claiming that we could always construct the word documents they wanted if "they" needed them. "They" never needed them.
I think alternative 2 is the less agile, because it means a new stage to the project (although it may be in parallel with tests).
If you are in an agile model, then just add documentation (following a guideline) as a story.
If you are in a staged approach, then I would nevertheless ask developers to work on documentation, following some guidelines, and review that documentation along the design and the code. Eventually, you may have a technical writer reviewing everything for proper English, but that would be a kind of "release" activity.
I think you can use Sand Castle to document your project.
Check it out
Sand Castle from Microsoft
It's not a complete documentation, but making sure that interfaces etc. are commented using Doxygen-style comments means writing code and documenting it are closer together.
That way, developers should document what they do. I still think a review by the architect(s) is needed to ensure consistent quality, but ensuring people document what they do is the best way to ensure they follow the architecture.