3 ms·
I blame the OOP culture for the idea that code is self-documenting (and also for the sibling idea that unit tests can replace documentation). See, OOP worldvie
by js8 4y ago
I blame the OOP culture for the idea that code is self-documenting (and also for the sibling idea that unit tests can replace documentation).
See, OOP worldview is a priori based on the idea that all programs can be written as collections of small, independently reusable, objects. In that world, there is no place to put any high-level explanation of how the parts interact as a whole, or what are any emergent properties of the system, because it is (on the ideological assumption of object independence) not needed.
It's very visible from e.g. Java package system design, there is no place to document what a particular package is for, or what classes are part of its public API and what are internal. And in Java in general, every entity must be assigned to some object, the things that lie outside (and can be shared) are frowned upon.
- koreth1 4y agoIt seems like some of these issues with Java are out of date. Java has had a well-defined place for package-level documentation for close to 20 years, since 1.5. It goes in package-info.java (docs: https://docs.oracle.com/javase/6/docs/technotes/tools/solaris/javadoc.html#packagecomment https://docs.oracle.com/javase/6/docs/technotes/tools/solari...). As for documenting which classes are part of the public API, you've been able to make classes package-private since Java's initial release. The module system introduced in Java 9 in 2017 takes that further; you can explicitly control which classes are exported to consumers. "Everything must be an object" is still more or less as true as it ever was, though.
- js8 4y agoThanks, wasn't aware of package-info. Yes, the module system is an improvement. Java is becoming more pragmatic as the ideological dominance of OOP is dying out.