Oct-23-2022, 07:01 AM
Are the users of your libraries generally also helping you develop them? I can see why documentation like that in that case is useful. Otherwise, users who aren't developing them are likely more interested in what the functions do, rather than how they're doing it. Good abstractions with good names and automated tests help this. Automated tests are better than comments for this sort of thing because they have the benefit that they will fail if the behaviour doesn't match. Well, should would be a better word. Tests need to be written in a way that actually check the code does what it's supposed to. This sounds obvious, but I've seen submissions for my company's programming test where candidates write tests, but all those tests do is check that no exception is thrown by the functions. This means they're useless, because you could write whatever logic in those functions, even create some bugs and the tests wouldn't fail.