I might be having a dumb day but today after looking over my code I ran into a meaning issue with my own syntax, and the comments explaining that syntax...something I've never actually thought about until I decided I need to be clearer to myself, as this application gets larger and larger and I'm the only maintainer on this project...so here is the question.
If I were to say merge hash1 with hash2 what would that mean to you? Would it be more proper to simply say "merge hash2 into hash1" since this is what I actually mean? I'm not the the only one reading this so I want to be as clear as possible to people who aren't programmers what exactly is going on.
For anyone who wants elaboration on entities:
hash1 = {a: "default", b: "default", c: "default"}
hash2 = {a: "new", b: "new"}
Where in this case hash2 is being merged into hash1 so that hash2 overrides hash1.
For anyone who doesn't program, think of it as two lists, list2 merging into list1.
Answer
As a programmer (American) I agree you need to clarify your comments in the code. When I can't understand my own comments (and it has happened), I'm in big trouble.
I would expect merge A with B to give a result that contains all the elements of both A and B, but it doesn't tell me if the result is in A, B, or C. Merge A into B tells me that B will end up gaining anything from A that wasn't already in B.
In your specific case, I would say update hash1 with hash2 because you are modifying hash1 by ensuring that it contains the data from hash2.
It would probably be beneficial to use more than four words because someone else may eventually maintain the code and explicit comments will be greatly appreciated.
No comments:
Post a Comment