Skip to content
This repository has been archived by the owner on Sep 10, 2022. It is now read-only.

Improve variable naming throughout the whole code base #147

Open
martinda opened this issue Aug 23, 2020 · 1 comment · May be fixed by #178
Open

Improve variable naming throughout the whole code base #147

martinda opened this issue Aug 23, 2020 · 1 comment · May be fixed by #178

Comments

@martinda
Copy link
Contributor

The application would benefit from following the common practice of naming instances after their type. Specifically, class names and instance names should be a complete string match except for the first letter which is upper case for the class and lower case for the instance. To put it bluntly this is good: GoodClassName goodClassName, and this is bad: GoodClassName otherName.

I would also recommend naming URL paths and methods that implement them exactly the same way.

Here are examples I find in the code where names can be improved:

  1. private transient final PackageConfigGenerator packagerConfGen
    1. "packager" and "package" do not mean the same thing, packager suggests it creates a package, while package is the object being created
  2. this.packagerConfGen = packageConfGen -> suggest that the creator becomes the object it creates, which is not possible
  3. PackageConfigGenerator packageConfGen: should be PackageConfigGenerator packageConfigGenerator
  4. PackagerDownloadService packagerDownServ: should be PackagerDownloadService packagerDownloadService
  5. /getPackageConfiguration and public ResponseEntity<?> getPackageConfig(...): the method name should match the URL path
  6. /getPackageConfiguration and /downloadPackageConfiguration: these two are nearly indistinguishable without reading through the whole javadoc, and even then it is still not obvious (perhaps the name could say more, like getPackageConfigurationFrom...).
  7. PackagerController.java and PackageControllerTest: the problem is that "Packager" and "Package" are two different names with two different meaning, so at a quick glance, the person reading the code gets the wrong idea that there is also a PackageController.java and a PackagerControllerTest.java, which is wrong in this case.

Why is this important? During code reviews and while bug hunting, the programmer has to build keep in mind a map of names. When names match, it is easier to build a mental representation of the code. When names to not match, building this mental representation is a lot harder because the map also needs to account for variable name translations (packager -> package, etc.).

Names are of the utmost importance in code maintenance and longevity.

@iqbalrohail
Copy link

hello sir,
I am a beginner to open source and would love to work on this. I am much familiar with the naming conventions of java and can solve this issue. So, can I work on this?

@iqbalrohail iqbalrohail linked a pull request Jun 7, 2021 that will close this issue
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants