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.
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.
“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.
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.
If you’re not that familiar with the language, it’s likely you won’t be contributing to the project.
You can still borrow and implement features developed by project x into project y , but I do understand the time limitation.
because I am more of a visual learner I wondered whether developers don’t use diagrams and flow charts, or just don’t include them in the docs.
Personally I will jot some loose notes down if I’m implementing something thats sufficiently difficult, but formalizing the design patterns/algorithms is very time consuming so I don’t.
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
Edit; from your other comments, you seem to be talking about protocols, not algorithms. An algorithm is a set of steps to do something. A protocol is a description of how different systems interact such as in a chat application.
I think you’re describing protocols rather than algorithms For a chat program you can look at xmpp, or matrix, both are open protocols for chat apps. You can find info about how they communicate in RFCs or Google “xmpp architecture”
https://en.m.wikipedia.org/wiki/XMPP links to the RFCs for that.
Most software is poorly documented. That applies to FOSS as much as to commercial projects.
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!
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?
I think they mean like a flow chart or another visual aid to show data changes and information flow through a program. Ive never seen anything like what they are asking for either in documentation, only in code meetings or developer charts.
Exactly what I was referring to. its the type of flow charts you find included in some whitepapers as well.
The problem with stuff like flow charts is that when you do a new feature that changes the chart then there’s another chunk of time to update that document. If you’re really interested in that all you can really do is make your own as you go through software and you’ll see usual patterns how different code areas interact. it’s not as useful as figuring it out on your own or studying design paradigms.
No, I haven’t started my project yet. I was looking for docs with descriptions and diagrams about server-client chat algorithms. And I haven’t found any, that’s why I am asking!
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.
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.
You are really looking for architecture diagrams. These are extremely rare in most projects, open source or otherwise.
The reason you don’t see a lot of documentation on algorithms used or architecture is that most of the time the code is not actually novel. It’s like asking a plumber to describe the physical properties of the pipe they used on a job. They’d say “schedule 40” or “copper” and a dimension. They would not describe the manufacturing process or chemical composition of the pipe. The materials are pretty standard and only require special descriptions for when and why they deviate from those standards.
