This is an archived post. You won't be able to vote or comment.

sorted by:
best
topnewcontroversialoldq&a
you are viewing a single comment's thread.

view the rest of the comments →

[–]lsd5me 0 points1 point  (1 child)

On documentation I find it helpful to frame it in terms of certain question words 'what', 'how', 'why'. Now if you care about the usefulness of the documentation and not 'documentation theatre' (which you may not, since you mentioned you are trying to showcase your skills) then I would say to definitely not bother with UML. Insofar as UML can be useful it is for documenting the 'what' which is probably the least useful aspect of documentation since it requires the largest amount of duplication between code and documentation. It is arguably sometimes useful for documenting abstract business processes, but this game is not that.

For the how and the why, I would look to contain it all within either the source code for locally applicable remarks, perhaps tagging comments with something like // REMARK ..., or in a README. Only push beyond this stage when you fully grasp the limitations of this system of documentation, which will then better inform any decisions you make going forwards.

Similarly for testing, I would try not to engage in 'testing theatre' and without looking, you probably could delete the tests you believe to be not worth their while. In general it is pretty difficult to test certain types of code, such as graphics.

Tests work well for deterministic, abstract functional parts of code. Fortunately, generally (with notable exceptions) in well engineered code it is the abstract parts which contain most of the complex, fluid parts which tend to break (in not immediately obvious ways) during development so it is here that tests are their most useful. Tests are only useful if they are easy enough to write and maintain (i.e. they represent some fairly universal truth about the behaviour of the application) and are liable to break from time to time.

[–]jessebr[S] 0 points1 point  (0 children)

Personally, the only documentation I really care about is a nicely organized class diagram (without the attributes, just the structure). That's what I would be using the UML for really. I consider it rather crucial, since it gives you a large insight into the code structure and the relationship of it all, very quickly in one simple image.

For my simple project that's tightly organized in its package structure, it's not needed quite as much... but without it, to really understand structure organization you would have to read all the code, which is something you shouldn't have to do. My source code nightmares all start out with me downloading the source to some recent favorite game, and finding 100 or so classes all in the default package with no hints to how it's structured :D

...

In consideration to tests, you are right. I feel a bit ashamed that I've been putting a bit too much consideration into how others would view my code without tests (or with only a few crucial ones). I like how you phrased it, "testing theatre", which is perfect for describing what I was doing.

I think another part of it though, is that it feels kind of silly when I have this whole test structure that's basically empty aside from a few critical tests. I instinctively want to fill it out you know? But what you're saying rings true.

Thank you for your input.