Disclaimer : I am a hobbyist programmer, I have not gone to Uni for that , so I might not know everything I am talking about.
My question is why don’t open source programs include something like diagrams of the algorithms they employ ?? I Was looking for algorithms for a chat program with client-server architecture, I was hoping to find diagrams and descriptions of how algorithms work, so a to study them an adapt them to my needs. All I found were FOSS projects with no such documentation.
Considering that reading source code can take a long time, and sometimes interesting projects are written in a language the user isn’t familiar with, I was wondering why such documentation style doesn’t exist ? It could help even newer contributors get started quicker.
At the end of the day it’s a lot of effort.
People are already giving up their free time to write code.
Very few companies even have this.
I am in the habit of writing verbose comments in my source code, which includes attributing the algorithms used and where I found information thereon. Unfortunately, this is not common practice… Be the change you want to see!
The answer to this question is the same as for all documentation:
- Because it’s boring to write documentation
- What is obvious and what needs to be explained is often not apparent for the person creating it
- When time is limited then documentation is the first thing to be reduced
- Not enough value is put on good documentation and the associated skill
But in the spirit of FOSS documentation is something that is actually an excellent thing for a person new the project to start contributing to. You need to understand the code anyway to be able to help with bugfixes / feature creation so might as well build reputation by improving on existing documentation by adding clarification and comments and wiki entries that would’ve aided in making it quicker for you to grasp something.
Also, it’s not just that it’s boring, difficult, and undervalued, but also during development the code is constantly changing and to constantly spend 20 minutes updating documentation for a 3 minute change that might or might not solve an issue is horribly wasteful of time. So by the time a project releases, probably 80% of the documentation is outdated already.
The only exception to this I’m familiar with (though I’m sure there are others) is using OpenAPI to generate both source code and documentation from a configuration file. That way your documentation and code are always in sync. But that’s a relatively narrow use case that isn’t going to cover low-level stuff like algorithms.
Considering that reading source code can take a long time
You’ll get faster over time, until reading code is faster than reading documentation, as code will always represent what’s truly happening, while docs are frequently outdated.
In a language the user isn’t familiar with
If you’re not that familiar with the language, it’s likely you won’t be contributing to the project. Open source projects usually to have quite limited resources, so they tend to optimize docs and dev UX for people who are likely to contribute.
I’m very unclear about what you’re asking. Do you have an example of something you’ve created that includes what you’re talking about?
“algorithm” is a little too fine grained for what you describe. “software design patterns” is probably what you are looking for.
unfortunately, not all projects call out the patterns they employ.
There are a lot of books describing algorithms. Most network protocols are described in RFCs as well as advices on their implementation. So you are looking in the wrong place. Source code documentation is usually enough to be understood by coders who are already familiar with common algorithms, protocols and APIs or know where to find their description. Only things that are very specific to the project can be described in details.
Being able to document the exact algorithms used to solve a problem is sort of a ‘Holy Grail’ in programming. Most programmers aren’t afforded the time to document to that level. This would require refining the code down to a single cohesive story that describes the functionality of the implementation. It’s great when you can spend the time on it, but the problem is that the code is actually “working” long before that point. Most employers want to stop paying for code after it starts working.
There’s no point spending twice the time making something that corresponds 1:1 to code - unless the code is truly horrific, and then you’ve got bigger issues. One generally assumes people involved with a project will know or learn relevant languages.
It’s more commonly used for things that are less obvious from the source itself - like “what’s sent between the client and server in this handshake” or “what is the overall architecture of this part of the code”
Flowcharts may be a bit more common when studying algorithms in general
Most software is poorly documented. That applies to FOSS as much as to commercial projects.
