How do you communicate and document your algorithms to others?

One thing I've found helpful is when people keep the comments within the code updated as the code goes through multiple iterations of change. In addition to that, linking a clean design document to the code check-in helps answer any other questions that may arise and help set broader context.

10 seconds summary of all the content and comments: Make sure you include/use the following to communicate: 1. Diagrams 2. Comments 3. Pseudocode 4. Unit tests 5. Naming the methods properly even if it's verbose

I've heard so many complaints about how commenting isn't important because "it's obvious that getWidth() gets the width of the shape." I then usually follow up with several questions like "is the width in inches, pixels, meters?", "does the width change as the shape is rotated?", and "can the width ever be zero?" When I've asked questions like that it usually takes a while for the developers to determine the answer. That time could have been saved by having better comments. Code is never self documenting, even if "getWidth()" had returned an "constant axii_aligned_meter_measurement" type. Code is for the compiler, comments are for everything else.

The challenge of documentation is that it eventually gets out of sync with the code. Thus, if we can make code as self-documenting as possible by using easily recognizable patterns, descriptive names, and clear formatting, we can answer most questions about it inline. Tricky, domain specific aspects, can be documented in comments. Complex algorithms can be documented with a link to their paper. External project documentation should only be depended on as a last resort. I've rarely seen such documentation being kept up to date with code changes. Documentation is usually updated frequently prior to the first release after which it tends to not be updated at all. No engineer has ever been promoted for maintaining documentation.

The best way to include examples with code is to include them as unit tests. This way they both verify and document how the code is supposed to work. Be very suspicious of any code checked in without unit tests.

A good way to document algorithms is by putting their pseudo code in comments before the actual code that implements the respective pseudo code step. This allows a reader to get an idea about the algorithm without having to interpret the code. The reader of a code can eventually figure out what the code does, but he cannot tell what the code was supposed to do unless the writer makes his intention clear somehow. Descriptive names, comments, and unit tests can document what the code was meant to do and they can help readers figure out how to fix it or extend it.

Pseudocode is a high level way of describing what your code does in natural language w/o the level of formality and detail required by a programming language. You can abstract chunks of code. For instance, if you are loading a .csv for processing, it's not necessarily helpful to include six lines of boilerplate, instead we can write "load .csv file into dataframe" Here's pseducode for an algorithm I wrote to compute the cohomology of a G-simplicial complex: - vertices = polyhedral fundamental domain F - refine by computing fix points of G action: - get rep'n sig=g.matrix() - compute fixed = null(sig - id) #solves sig.x = x - compute intersection F and fixed - add new vertices to list - return simplicial cohomology

Comments should be used only after exhausting the possibility of using descriptive names (for methods and variables). A good use of comments is for including the pseudo code of algorithms, which helps readers process code faster.

As already mentioned, the best way to document your algorithm is to bring out a research paper on the same. This in turn would bring out a structure to the whole process of communicating your idea to the world. The process involves subdividing the presentation of your idea into various sections. These are 1. Introduction - You introduce the problem to the readers in the most understandable manner. 2. State of the art in the field 3. The efficacy that your algorithm brings in and its impact. 4. Algorithm explanation along with relevant control flow diagrams/ flow charts and pseudo code 5. Results based on validation against benchmark data sets. 6. Summarisation with a note on areas to extend/improve.

Unfortunately, most organizations don't reward code that was well written; they only reward the functionality delivered (more precisely, the functionality that they think was delivered), which provides no incentive for writing good code especially for people that don't plan to stick around in a place more than a couple of years. The fact that code cannot be delivered on time because the code base is not well written is only taken into consideration when the delays become too significant and by that time the cost of solving the issue also becomes significant.

Good coding practices definitely include adding comments to your code, adding unit tests. Additionally, having a README file is a smart move. It's like the user manual for your code module. A well-written README can give new users a clear understanding of what your code does, it's a great way to provide a history of the structural changes to the project.

Sometimes, the best way to communicate an algorithm is to yell it loudly at others, then berate them for failing to understand.