3 ms·
> Have you ever looked at a very large project > You are making everyone else's life a nightmare. I work on code touched by tens of thousands of other enginee
by echelon 6y ago
> Have you ever looked at a very large project
> You are making everyone else's life a nightmare.
I work on code touched by tens of thousands of other engineers. In my experience, code without comments is typically structured, easy to read, and does exactly what is written. Code painted top to bottom with comments tends to be muddied, confusing, and more junior in nature.
The shape of solutions is common. You're not reinventing the wheel with every new project. Engineers are familiar with the design patterns, frameworks, and algorithms you use, so you don't need to force a context switch to point them out.
You can use the symbols themselves as a form of documentation. Instead of having an entire algorithm inline, individual queries or processing steps might be put into their own self-documenting methods:
verifyMarkdown(article_rating: &Rating)
upsertRating(article_rating: &Rating, author: &User, transaction: &Transactor)
publish(article_rating: &Rating, transaction: &Transactor)
enqueueSubscriberNotifications(author: &User)
Small pieces of code might not require a functions to wrap them, but by naming small units of behavior, you can communicate your algorithm step by step without comments.
This is only one type of communication technique you can use. There are bountiful ways to improve your clarity.
I apologize if my examples are obtuse. It's late.
- axegon_ 6y agoOK, good points, but my argument stands in most cases: It doesn't matter how experienced a developer is. You'll rarely see anyone as pedantic as I am when it comes to conventions, structure or organization, but there have been multiple instances when I've had to cut corners to meet some deadline. I work on an enormous projects with few developers. Say we all decide to go full Eric Cartman tomorrow and call it quits. Guess how long it's going to take someone else to work their way through 8 years of development without a single comment? My bet - they would keep hitting rocks day in and day out. In the case of thousands, the likelihood of everyone leaving at the same time is much lower, but I'll go back to my postgres example, which I genuinely use as a benchmark as far as code goes. If everyone abandons it today for some reason, everything is so well thought out, well structured and documented that new people can jump in right away and the development won't be slowed down dramatically, granted that the new developers follow the current process.