If you do this you will be adding a new layer of expression to the existing pile. A layer that allows you to express your preferred working perspective, but sti

If you do this you will be adding a new layer of expression to the existing pile. A layer that allows you to express your preferred working perspective, but still, the other layers came with working philosophies too. Expressive and unique code often expresses a set of general workplace-system values. It's like a T-shirt with an obscure slogan on it. You propose to add an explanatory note to the T-shirt, in a way. To some, that's helpful. To others it's a metaphorical marketing disaster. (You explained what, to who?? Man, don't do that for them, they don't deserve it and don't know what they are doing.) In those shoes, I would ask myself if the current leadership and philosophy of the inner-company has really changed since Perl times and if you have buy-in to take control. Or if you will be packaging control systems for people up the chain who will take that control and use it to wield _you_ more directly. (Perl in such a state as you found it was a great equalizer in those cases. It helped raise the level of technical discourse to where we are at now, in a big way, by allowing this unique prose as code. You want a seat at the table, earn it with technical chops, and this will be future-proofing in that sense) From a peer perspective, what your documentation indicates to code-expressive personalities (people) is that you intend to focus on broad, systems-level control. This can be really scary to them and maybe also laughably grandiose, and can cause reactions you don't want. So I couldn't tell if you are working with anybody like that, but if so it's something to consider. You should at the very least take stock of who else documents, and who doesn't. Overall: If little documentation was done, and you are heavily pro-doc, you need to consider that this is a complete shift in philosophy in some deep ways. If you are the variable here, yikes, look out, you could be giving your peace of mind or maybe your job away in exchange for equity that is not really there waiting for you. But if there's some other variable like new ownership, maybe not so much. Maybe broader systems-control is needed of you at some more primal level, e.g. it stands between you and the literal destruction of the org. Future-proofing is also great until you meet the next engineer who is fascinated by mainly details and who literally perceives the future as changing with every new discussion upstairs. So, which perspective does your organization reward and prefer? That's a good cue for a thoughtful or nuanced approach to the future. There are also different levels of documentation, such as documenting for yourself but not so much for others, and I think this is worth considering in lots of situations. Just some thoughts and good luck. P.S. It can be tempting to conflate being someone who practices good documentation with being a good and helpful person. This may be true in some cases, but it's also true that many organizations are long past the point at which this thought model was useful in isolation.