4 ms·

Comments should never be "what". They should always be "why".

zimpenfish 2y ago
That works if the code wasn't written by, well, lunatics who decided that clear simple code was The Work Of Satan and if you couldn't have a tower of interfaces or write your own bafflingly complex ORM, what was even the point? Then the people who follow will almost certainly need some "what" commentary (as well as the "why" but IME the lunatics who spurn clear and simple code never think they have to explain "why" either.)
- mschuster91 2y ago
  > or write your own bafflingly complex ORM Oftentimes, the reason for that is that 20 years ago stuff like Doctrine, Liquibase or whatever just didn't exist. You know, the time when PHP developers shipped straight mysql_query calls with direct interpolation of $_GET, and most "enterprise" Java application came with a ton of SQL scripts and a dedicated multi page UPGRADE file explaining in which order you had to run the schema migrations, reboot systems, run manual migration scripts and whatnot to get an upgrade done. Some times, upgrades could literally take days. Naturally, people invented their own stuff to make stuff just suck a little bit less, and it got more and more used in a company, only ever extended in functionality... the dreaded "corpname-utils" JAR dependency (if you're really unlucky, the JAR having been semi-restored from a half-broken decompile because the sources got lost along the way) or util.php that just got copied over from project to project. And that's how you end up in 2024, still maintaining some ORM that has its origins in Perl code written in the 90s by someone deceased in the '00s. (Yes, I've been there, although not that bad)
  - pantulis 2y ago
    > the dreaded "corpname-utils" JAR dependency In my first job, my older colleagues, most of them now managers, had managed to write their own library. It included its own timezone management, a wrapper o top of DEC's OSF/1 AXP concurrency primitives, a realtime memory-mapped database format, a compiler that run not on files but in expressions stored in an Oracle databse, and even their own CORBA-like object sharing over TCP/IP. These people were wizards, and probably did a lot of stuff just to show their coding prowess, but a decade later when I joined that company most of the younger programmers did not dare to touch that code. I had to do that when the software was being deployed in Brazil, where nobody had expected how DST changes in the south hemisphere.
  - zimpenfish 2y ago
    > Oftentimes, the reason for that is that 20 years ago stuff like Doctrine, Liquibase or whatever just didn't exist. Sadly I am talking about something written in Perl (blessed with ORMs since at least 2001) around the early-mid 2010s. Not a single reason it should have been written. The only thing it gave us over well established Perl ORMs were code that no-one understood, no support for that code, and a panoply of infuriating bugs that constantly broke production.
edflsafoiewq 2y ago
Comments should be whatever you think warrants commentary. If that's "what", that's fine.

That works if the code wasn't written by, well, lunatics who decided that clear simple code was The Work Of Satan and if you couldn't have a tower of interfaces or write your own bafflingly complex ORM, what was even the point? Then the people who follow will almost certainly need some "what" commentary (as well as the "why" but IME the lunatics who spurn clear and simple code never think they have to explain "why" either.)

mschuster91 2y ago
> or write your own bafflingly complex ORM Oftentimes, the reason for that is that 20 years ago stuff like Doctrine, Liquibase or whatever just didn't exist. You know, the time when PHP developers shipped straight mysql_query calls with direct interpolation of $_GET, and most "enterprise" Java application came with a ton of SQL scripts and a dedicated multi page UPGRADE file explaining in which order you had to run the schema migrations, reboot systems, run manual migration scripts and whatnot to get an upgrade done. Some times, upgrades could literally take days. Naturally, people invented their own stuff to make stuff just suck a little bit less, and it got more and more used in a company, only ever extended in functionality... the dreaded "corpname-utils" JAR dependency (if you're really unlucky, the JAR having been semi-restored from a half-broken decompile because the sources got lost along the way) or util.php that just got copied over from project to project. And that's how you end up in 2024, still maintaining some ORM that has its origins in Perl code written in the 90s by someone deceased in the '00s. (Yes, I've been there, although not that bad)
- pantulis 2y ago
  > the dreaded "corpname-utils" JAR dependency In my first job, my older colleagues, most of them now managers, had managed to write their own library. It included its own timezone management, a wrapper o top of DEC's OSF/1 AXP concurrency primitives, a realtime memory-mapped database format, a compiler that run not on files but in expressions stored in an Oracle databse, and even their own CORBA-like object sharing over TCP/IP. These people were wizards, and probably did a lot of stuff just to show their coding prowess, but a decade later when I joined that company most of the younger programmers did not dare to touch that code. I had to do that when the software was being deployed in Brazil, where nobody had expected how DST changes in the south hemisphere.
- zimpenfish 2y ago
  > Oftentimes, the reason for that is that 20 years ago stuff like Doctrine, Liquibase or whatever just didn't exist. Sadly I am talking about something written in Perl (blessed with ORMs since at least 2001) around the early-mid 2010s. Not a single reason it should have been written. The only thing it gave us over well established Perl ORMs were code that no-one understood, no support for that code, and a panoply of infuriating bugs that constantly broke production.

edflsafoiewq 2y ago

Comments should be whatever you think warrants commentary. If that's "what", that's fine.