What makes it easy to use .NET Framework (except some dark parts)?
- The documentation (MSDN) is easy to access, complete, detailed, but not too overloaded with stuff you never need to know,
- The community (StackOverflow and some forums, including Microsoft ones) can answer most questions,
- The API is uniform, clear to understand even without documentation, logical (you wouldn't search
System.Diagnostics for file I/O methods) and designed by experts.
You see that the documentation is only a part of a whole infrastructure needed to understand some piece of code to be able to reuse it: community and code quality are not less important then good documentation.
In most cases, when you develop a standalone component inside a company a bit smaller than Microsoft, once you have a high quality, refactored code, there are two things which can help for the documentation:
- Detailed documentation embedded in source code (description of every method with their parameters and return values, summary of every property and every class, etc.)
- Summary document explaining what is the project, what is it intended about, how it is structured, and what architectural choices were made and why.
With this, it must be pretty easy to start to work with an existing codebase.
Also note that some features of the language can strongly enhance the understanding of your code. Code contracts, as used in .NET Framework, are a good example, since they provide detailed and exact, always up-to-date information about what a method accepts as parameters, and what it returns.
Some bad practices, on the other hand, can make it impossible to work with the codebase. For example, returning error numbers as a return value of a method instead of doing things correctly (using exceptions) have strong chances to make the overall code unclear and difficult to use, even with highly detailed documentation.