This is a question for those people who have developed a SharePoint solution and made it available for public consumption, such as:
What were the main lessons learned and best practices you found specific to developing a broadly-used SharePoint solution?
Any experiences valued. Thank you.
I gave your questions some thought, Alex, and I came up with a short list of things I focus on. For the record: I make it a point to focus on these items regardless of whether or not a project is for a specific client (private) or "public consumption," but I view the following items as critical.
I operate under the assumption that someone might try to learn something from what I've put together, and so my overarching goal is to provide as much insight and description as possible into the workings of my software. Whether someone learns by deconstructing, analyzing, playing, or simply reading, I try to afford the same experience I would like when learning from someone else's projects/efforts.
DESIGN PATTERNS
I'm a design pattern junkie of sorts, so I try to implement good software design patterns (Gang of Four, Martin Fowler, etc.) where possible. I try to think about where my software might be extended by others and then supply hooks/extension points to do so. It certainly adds additional overhead, but if the assumption is that the code will evolve, a small investment up-front can save tremendous rework and re-factoring later. I'm sure that there are plenty of TDD folks out there who would disagree with such an approach; hopefully, they'll share their thoughts, as well!
DESIGN DOCUMENTATION
If I'm going to put something into the public domain, I want to put my best foot forward and demonstrate a little forethought and rigor. I develop my designs using a modified MDA approach, so this step is a bit easier for me than for some of folks. I believe that external documentation should generally include one or more of the following: class diagrams, sequence diagrams (for potentially confusing interactions), activity diagrams for complicated logic, packaging diagrams (to help explain what's in a WSP, for instance), and anything else that helps to flesh-out the "big picture" before code starts coming together.
If someone doesn't design first but wants to release to the public domain, I would push them to at least go back in after the fact to get the "low-hanging fruit." Visual Studio is great at creating simplified class diagrams, so do so. Describe interactions between pieces of the solution in plain speak. At a minimum, put something together that helps folks understand what was going through your head at the inception.
INTERNAL DOCUMENTATION
Internal documentation is a big thing for me personally, and I push all of my team members and peers to put usable code comments in. Personally, I think it's professional negligence not to do so ... and that goes doubly for any code that will ultimately be released for public consumption or scrutiny. In my experience, many developers don't include comments simply out of laziness. It isn't until they're forced to consume someone else's code (which is devoid of comments) or their own older code (also devoid of comments) that they sometimes start to see the importance.
By the end of a project, I have XML comments in place to generate meaningful help files (.CHM) via SandCastle. For me, the comments are as important as the code itself -- and sometimes moreso. I comment as I go, and I try to share my mindset, insights, and targets as I write code. In my experience, this approach really helps speed comprehension for those picking up the code fresh -- especially if what I'm releasing is an application framework for others to use as their own building blocks.
SETUP/USAGE INSTRUCTIONS
If the SharePoint solution is going to be released into the wild as a compiled and ready-for-use product, I like to put together at least some basic usage instructions that target an admin. Most admins can install and deploy a WSP these days, so not a whole lot of writing needs to go into this type of document unless there are some unusual aspects, manual steps, or dependencies with the install.
PACKAGING AND DEPLOYMENT
While I'm on the topic of WSPs and Features ... I feel that they should be leveraged to maximum effect to remove manual anything from the setup process for all "finished product" releases. I don't ask an admin to hack a web.config file; I use SPWebConfigModifications in a FeatureReceiver. I don't force an admin or user to create lists or columns; I provision them through CAML or code. If for some reason something can't be packaged or automated, I do everything possible to simplify the life of the person stuck with the manual work. They (sometimes) thank me later (or at least avoid cursing me and my children).
VERSIONING
For released products, I try to have a solid versioning strategy. I try to make sure I have relatively good release notes and explain why something was a minor version release vs. a revision vs. a major release. If I'm planning a fix or have a product roadmap (a good idea, generally speaking), I try to include it.
BE AVAILABLE
If I put it out for others to use, I try to make sure that they know how they can find me to complain (or say "thanks" -- that's always nice, too). These days, this isn't quite as big an issue as it used to be. Social networking is everywhere, CodePlex has feedback mechanisms built in, etc. I just try to be responsive.
DO UNTO OTHERS
Above all else, I try to be honest and straightforward with the folks who are reading my code, running my software, and trying to learn from what I've put together. If something works but I simply don't understand why, I call it out (and ask if anyone else knows). If I recognize something is buggy in what I've done, I spell it out ... and then try to find a more robust way of doing it. It sounds simple, but I try to do things the way I would want them to be done for me. That can be hard at times, and it can certainly lengthen design and development timelines, but I think the end result is worth it.
TO SUM IT UP ...
I hope none of this comes off as too "preachy." It's just my personal take and opinion on the process of developing software and releasing it -- nothing more. My method works for me, and I think aspects of it work for many. I highly encourage dissenters to share their thoughts, as there is always more than one way to skin a cat :-)
Useful online references: