4 ms·

Your term may not map cleanly to a single OOP class, and it may also be used in other function/variable names. There's also how you will express yourself in th

Your term may not map cleanly to a single OOP class, and it may also be used in other function/variable names. There's also how you will express yourself in the code comments. I mean, I'm guessing the dictionary is not just for nouns, but also verbs and adverbs. What will "transact" usually mean in this codebase? What will "safely" mean?

ffsm8 3y ago
> Your term may not map cleanly to a single OOP class That's not really an argument, as it will map to either entities or functions, both of which can be annotated with this information. An argument against documenting it on the entities and functions would be that this would spread the information across the repository. The value you get from doing this in a single markdown file is the overview it provides, I think. These kinds of methodologies enable development with high turnover in large enterprise, which treat developers more like cogs that temporarily work on a given software. And if it's just a comment on a file, it'll likely not even be seen
- coldtea 3y ago
  >That's not really an argument, as it will map to either entities or functions, both of which can be annotated with this information. No, it might not map to entities or functions. It could refer to concepts about the project that are not mapped in the code, but are still important to communicate with the team, the customers, and so on. And even for terms that do map to entities and functions, it would be a bad idea to have the developers (and especially non developrs) hunt them around (even if it's just a grep away). As you say, the overview is important. >These kinds of methodologies enable development with high turnover in large enterprise, which treat developers more like cogs that temporarily work on a given software. Even small teams of 4-10 people can benefit from shared common terminology, especially if each might work in different repos (or e.g. backend and front-end).
  - ffsm8 3y ago
    > Even small teams of 4-10 people can benefit from shared common terminology The team size has very little impact on it's value, it's entirely dependent on the turnover of the developers. I guess I wasn't clear enough as it seems you didn't understand what I meant to express at all. With every sentence you wrote I just had another question mark appear over my head
    - coldtea 3y ago
      I'm not sure what you think I didn't get - or what new questions appeared over your head. It's quite simple. You said 3 things: 1) You answered to the parent that whether "term may not map cleanly to a single OOP class" doesn't matter, because "it will map to either entities or functions". My answer was that it might not map to those either, but still be useful to talk about the software, and good to be shared by the developers and other shareholders like UX and sales. 2) That "An argument against documenting it on the entities and functions would be that this would spread the information across the repository", and having a single markdown file gives better overview. I agreed, and even expounded on that: "it would be a bad idea to have the developers (and especially non developrs) hunt them around (even if it's just a grep away). As you say, the overview is important." 3) That "these kinds of methodologies enable development with high turnover in large enterprise, which treat developers more like cogs that temporarily work on a given software. And if it's just a comment on a file, it'll likely not even be seen" And I retorted that even smaller teams - meaning teams that don't are anything like the above, including not having high turnover, can benefit from this. Even without any turnover, people forget. So when getting back to further develop or debug or refactor, etc, some piece software it's good to have documentation of key types, concepts, and terminology, from when you originally wrote it.

ffsm8 3y ago

> Your term may not map cleanly to a single OOP class That's not really an argument, as it will map to either entities or functions, both of which can be annotated with this information. An argument against documenting it on the entities and functions would be that this would spread the information across the repository. The value you get from doing this in a single markdown file is the overview it provides, I think. These kinds of methodologies enable development with high turnover in large enterprise, which treat developers more like cogs that temporarily work on a given software. And if it's just a comment on a file, it'll likely not even be seen

coldtea 3y ago
>That's not really an argument, as it will map to either entities or functions, both of which can be annotated with this information. No, it might not map to entities or functions. It could refer to concepts about the project that are not mapped in the code, but are still important to communicate with the team, the customers, and so on. And even for terms that do map to entities and functions, it would be a bad idea to have the developers (and especially non developrs) hunt them around (even if it's just a grep away). As you say, the overview is important. >These kinds of methodologies enable development with high turnover in large enterprise, which treat developers more like cogs that temporarily work on a given software. Even small teams of 4-10 people can benefit from shared common terminology, especially if each might work in different repos (or e.g. backend and front-end).
- ffsm8 3y ago
  > Even small teams of 4-10 people can benefit from shared common terminology The team size has very little impact on it's value, it's entirely dependent on the turnover of the developers. I guess I wasn't clear enough as it seems you didn't understand what I meant to express at all. With every sentence you wrote I just had another question mark appear over my head
  - coldtea 3y ago
    I'm not sure what you think I didn't get - or what new questions appeared over your head. It's quite simple. You said 3 things: 1) You answered to the parent that whether "term may not map cleanly to a single OOP class" doesn't matter, because "it will map to either entities or functions". My answer was that it might not map to those either, but still be useful to talk about the software, and good to be shared by the developers and other shareholders like UX and sales. 2) That "An argument against documenting it on the entities and functions would be that this would spread the information across the repository", and having a single markdown file gives better overview. I agreed, and even expounded on that: "it would be a bad idea to have the developers (and especially non developrs) hunt them around (even if it's just a grep away). As you say, the overview is important." 3) That "these kinds of methodologies enable development with high turnover in large enterprise, which treat developers more like cogs that temporarily work on a given software. And if it's just a comment on a file, it'll likely not even be seen" And I retorted that even smaller teams - meaning teams that don't are anything like the above, including not having high turnover, can benefit from this. Even without any turnover, people forget. So when getting back to further develop or debug or refactor, etc, some piece software it's good to have documentation of key types, concepts, and terminology, from when you originally wrote it.