Of all the ridiculous ideas!Seriously, no one is asking you to write War and Peace.
But, what you can do is write down the primary actions, validation, and error-handling, in a simple flow.
The client calls the API endpoint /someurl/object/{id}The API controller uses {id} (an int) to search for the object in question in the database.
If the object comes back null, the API controller returns a 404 (File Not Found) HTTP response to the client.
The API controller logs this as a warning.
If the object is NOT null, the API controller converts the object to JSON format, and returns it with a 200 (OK) HTTP response to the caller.
That’s hardly difficult, and also means that you’ve made someone else’s life easier.
If you’re interested in more selfish motivations, then writing this down means when people want help, you can point them to the doc, and not have to explain it again and again every time someone asks.
Step 2: Make some diagramsIf writing simple documentation is too difficult (please!), then at the very least, consider creating some diagrams, as these often give the glue necessary for someone to bridge your code with what is going on.
Have a look at websequencediagrams.
com, which offers a simple textual format for creating great sequence diagrams.
The texttitle Service one to service twoService two requester -> Service two http client: Get ContractService two http client -> Service one REST API: GET /api/contracts/{123}Service one REST API -> Service one app logic: get Contract with id 123Service one app logic -> Service one REST API: ContractService one REST API -> Service one REST API: Serialise to JSON / XML / etc.
Service one REST API -> Service two http client: Serialised dataService two http client -> Service two http client : Deserialise to ContractService two http client -> Service two requester: ContractThe diagram this producesThat’s nice!The old adage about a picture being worth a thousand words is correct.
Diagrams like this and others (such as a flow diagram) mean that non-programmers can learn about your app’s behaviour by reviewing a picture.
That’s value to your co-workers, and with little investment on your part.
Step 3: Use Ubiquitous Language to help the naming of your classes and actionsAs I outlined in another post, a Ubiquitous Language is a concept from DDD in which the team and users define a language of terms for all the classes and their interactions.
Such a language is human-understandable, so that customers, testers, trainers, and business people can agree upon and understand what our software is doing to fulfill our user’s problem domain.
Ubiquitous Language in your Software DomainDefining your software domain’s language makes everything easiermedium.
comOnce you have your Ubiquitous Language, you should make sure to name your classes, their methods, their events, everything, as closely to your Ubiquitous Language as possible.
This ensures that anyone reading your code (even non-programmers) can at least muddle through to some extent, as the programming structures align with terms and business concepts which they understand.
/// <summary>/// The Customer is responsible for their own login / logout, as well as retrieving their profile information, and management of their/// settings/// </summary>public interface ICustomer{ Task<AuthenticationResult> Login(string username, EncryptedString password); Task Logout(); Task<CustomerProfileInformation> GetMyProfile(); Task SaveMyProfile(CustomerProfileInformation); Task<CustomerSettings> GetMySettings(); Task SaveMySettings(CustomerSettings);}While still in code, the description at the top, coupled with the use of terms which are familiar to everyone, make it easy to understand what is taking place, because the terms already exist in our Ubiquitous LanguageStep 4: Just add some commentsIf all of this sounds far, far too onerous, then at the very least, just add some meaningful comments in your code.
You may not need them right now (you are down in the weeds, so of course the code makes sense to you), but in the future, you very well might.
A few well-placed lines of comments, a class comment, method comments, these go a long way to making what’s going on in the code far more understandable.
I’m not talking about commenting every line (that actually makes the code harder to read), but just hit the main or complex areas of the code, so someone can come along and work out what is afoot.
Hope this helps.. More details