this post was submitted on 17 Jan 2024
40 points (93.5% liked)

Programming

17522 readers
290 users here now

Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!

Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.

Hope you enjoy the instance!

Rules

Rules

  • Follow the programming.dev instance rules
  • Keep content related to programming in some way
  • If you're posting long videos try to add in some form of tldr for those who don't want to watch videos

Wormhole

Follow the wormhole through a path of communities !webdev@programming.dev

founded 2 years ago
MODERATORS
snowe@programming.dev
Ategon@programming.dev
MaungaHikoi@lemmy.nz
40
Algorithms instead of source code !! (lemmy.world)
submitted 10 months ago* (last edited 10 months ago) by erranto@lemmy.world to c/programming@programming.dev
19 comments fedilink hide all child comments
 

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.

you are viewing a single comment's thread
view the rest of the comments
[โ€“] ninjan@lemmy.mildgrim.com 39 points 10 months ago (1 children)

The answer to this question is the same as for all documentation:

  1. Because it's boring to write documentation
  2. What is obvious and what needs to be explained is often not apparent for the person creating it
  3. When time is limited then documentation is the first thing to be reduced
  4. 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.

[โ€“] MagicShel@programming.dev 17 points 10 months ago

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.