Timeline for The Don't Repeat Yourself (DRY) principle in documentation
Current License: CC BY-SA 4.0
9 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Jun 24, 2021 at 13:28 | comment | added | Doc Brown | @JacquesB: "But since these are separate implementations" - well, I did not look into the source, but from the OPs initial comment here, I assume the implentations themselves violate the DRY principle (intentionally), hence the docs do violate it, too. | |
| Jun 24, 2021 at 12:25 | comment | added | JacquesB | @DocBrown: The question is why the overloads are needed. This is probably due to a limitation in Java. If it was implemented as a single generic method or macro, then it should also only have the documentation texts once. But since these are separate implementations it is not a violation of DRY to have separate documentation also. | |
| Jun 24, 2021 at 12:02 | comment | added | Doc Brown | @JacquesB: sure there are implementation differences - they are pretty obvious: the basic type of the array and their default values. Everything else is identical, and the OP is asking if in such a situation, where 95% of the method behaviour is the same, and only 5% different, it is a good idea to duplicate the docs in full, or if one can try to write the 95% of the docs only once, and duplicate only the 5% part. | |
| Jun 24, 2021 at 11:48 | comment | added | iwis | @JacquesB: The copyOf() methods simply copy a table. This operation doesn't depend on the type of elements in a way other than allocating other number of bytes per element (byte 1B, short 2B, int 4B, long 8B, char 2B, float 4B, double 8B, boolean 1B), which is obvious, and the default value of the element type, which can be inferred. Apart of this the implementations are exactly the same. So your sentence "They happen have the exact same blurb currently, but this is incidental" is incorrect. | |
| Jun 24, 2021 at 11:32 | comment | added | JacquesB | @DocBrown: I'm sure they copy-pasted the same text. The point is the documentation for each overload does not describe the exact same thing since there are implementation differences. If the documentation had been more detailed the implementation details might have surfaced in the text. So the text are not equal by necessity, and therefore there is no DRY violation. | |
| Jun 24, 2021 at 11:25 | comment | added | JacquesB | @iwis: The key word is "almost". If they had the exact same implementation there would not be a need for multiple overloads in the first place. So there is some difference, and that difference may or may not be surfaced in the documentation. | |
| Jun 24, 2021 at 11:21 | comment | added | Doc Brown | Sorry, but I don't believe this is incidental. Quite the opposite, it is pretty deliberate. See my comment below this answer. | |
| Jun 24, 2021 at 11:21 | comment | added | iwis | "They happen have the exact same blurb currently, but this is incidental" - this isn't incidental, this is because they have almost identical implementation - see the source code of Arrays.copyOf(). | |
| Jun 24, 2021 at 11:16 | history | answered | JacquesB | CC BY-SA 4.0 |