Skip to main content
Software Engineering

You are not logged in. Your edit will be placed in a queue until it is peer reviewed.

We welcome edits that make the post easier to understand and more valuable for readers. Because community members review edits, please try to make the post substantially better than how you found it, for example, by fixing grammar or adding additional resources and hyperlinks.

Required fields*

7
  • ... BTW, I think your current approach of improving the documentation looks good. Who told you this is not a good practice? For me, "best practice" is to stay pragmatic and adapt any invested effort to the specific resources and needs of a project environment - it sounds you are already doing this. Commented Feb 7, 2024 at 14:54
  • @DocBrown I have updated the question text in yet another attempt to make it clear and focused. Commented Feb 7, 2024 at 15:21
  • One thing which bothers me is the content of the header. A high level description is good. Input and output descriptions are good. Nonobvious usage information or side effects are good. What I would avoid is to put anything into which can be easily retrived by anyone from source control, like creation date, original author or summary of changes. Commented Feb 7, 2024 at 16:26
  • @DocBrown - I get where your point comes from, and probably in most cases this is sufficient. However, not so long ago, I had to merge and migrate multiple SVN repos into one Git repo. Due to limitations of such process, sacrifices had to be made. Some of the metadata, including creation time and most of commit info got lost in the process. In that case at least the major "milestones" could be preserved in such header, as I would not want a commit history duplicate. BTW, what is missing for reopening my question? Commented Feb 7, 2024 at 22:53
  • There is a 3rd member missing with enough rep willing to cast a reopen vote. I casted my vote for reopening already yesterday. But to what you wrote: I would not duplicate the change history into the source code files just because there is a minimal risk in some years they history could be lost due to a change of version control (something for which the chances are quite low when you nowadays work with Git). I would instead invest a little bit more time into the migration process to migrate the meta data when it ever comes to that situation. Commented Feb 7, 2024 at 23:15