Welcome back to the Comment-pocalypse! (Go here if you missed the first part)

The next method of commenting, we surprisingly saw a lot of in the industry, is section commenting. It starts simple, with a question asked but almost any programmer after a bit of experience: What do we do in every function?

Well, we declare and initialize our variables that are then processed and then returned or passed through reference. What are these? Steps we take when creating a functionality, inside a function they are sections of code. This convention is simple, we simply add comments to each section so we know where everything goes. Let's look at an example:

function updateBread(newName) { // Initialize let serverMessage = { id: bread.getId(), name: newName }; let promise; // Process promise = fetch('/api/bread/updateBread', { method: 'POST', body: serverMessage }).catch(function(res) { alert('Failed to update bread') }); // Return return promise; }

This convention can be seen used with other section names such as: Declare or Setup, Act, Result The code looks fine (and so do the comments), we are initializing a few variables at first, sending a request to the server and returning the promise. Now let's add some more logic to this:

function updateBread(bread, brand) { // Initialize let updateMessage = { id: bread.getId(), name: newName, }; let brandId = brand.getId(); if (!brandId) { return; } // Process or initialization? promise = fetch('/api/brand/getPrice?id=' + brandId, { method: 'GET' }).then((res) => res.json() ).then((res) => { updateMessage.price = res.price; }); // Process promise = promise.then(() => fetch('/api/bread/updateBread', { method: 'POST', body: serverMessage }); }).catch(function() { alert('Failed to update bread') }); // Result return promise; }

Some of this convention is useful in that it forces data validation to be done first, before processing. The problem is that some snippets don't really go in either of these categories and it is quite subjective where you should place it. It is definetely processing data since it calls the backend with the validated variable brandId while it also initializes a message that is then processed later on.

This problem is not because we are using asynchronous calls, it is simply because most of the functions we create as a programmer act as a pipeline. A pipeline that takes the results of one thing and passes it on to another. That thing happens to be code in our case.

Another important aspect for this convention is that the return section is either redundant or ambiguous. Redundant if used like in the example... since you can simply see the return keyword. Ambiguous because if not used like in the example we would have to initialize or process data.

What does this mean? For the majority of cases we won't be able to bring all the initialization in one section and processing in another unless we are really careful with our functions. While our functions usually include each step, this convention doesn't account for functions that act as a pipeline which are usually the more difficult to understand ones. It's a shame, but this convention can really see much value when we have lots of initialization to do and only some processing.

What do you think? Can this convention have a really good use case? Leave your thoughts down below!