search

editorconfig / editorconfig.github.com

Configuration file format for defining coding styles in shared projects
http://editorconfig.org
Other
265 stars 42 forks source link

Clarify the first setence on the website to make it less ambiguous #106

Closed xuhdev closed 5 years ago

xuhdev commented 5 years ago

The first sentence is "EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs." This can be interpreted in two different ways:

  1. EditorConfig helps each individual developer define and maintain consistent coding styles between different editors and IDEs that the developer uses.
  2. EditorConfig helps developers involved in a specific project define and maintain consistent coding styles while they use different editors and IDEs for that project.

The meaning of EditorConfig, at least originally, lies in point 2. However, from time to time, we've seen users complaining or requesting features on the grounds of point 1. Do you think it is desirable to make the clarification?

jednano commented 5 years ago

I have some points that need clarification:

  1. What's the difference between "each individual developer" and "developers"?
  2. I think I'd rather see "that developers use" instead of "that the developer uses" as if there's only one developer on a project.
  3. It doesn't even have to be a specific project, because you can put an .editorconfig file outside of project folders (e.g., in your root GitHub folder).

I'm actually not seeing any problems with the original first sentence, so can you please point out the parts that are confusing?

EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs.

xuhdev commented 5 years ago

The difference between my Points 1 and 2 is that: Point 1 stresses on one developer who uses many different IDEs and EditorConfig serves as a configuration file for all of them. Point 2 stresses on one project in which many developers use different tools and EditorConfig serves as a practical code style specification. The rationale for focusing on Point 2 is that projects involving many developers can really get a lot of different editing tools involved, but it is fairly rare that a developer uses a huge amount of editing tools -- two or three different editing tools shouldn't be an issue because it is never hard to configure each of them and with far more detailed configuration.

The original sentence can be interpreted as meaning either. Instead, we really want to focus on Point 2 and, at the same time, try to help accommodate Point 1 as long as it doesn't impede Point 2 (e.g., your Point 3).

jednano commented 5 years ago

OK that makes sense. Might help to call out "multiple developers" just to hit home on that point. I think it also helps to reverse the language a bit. How does this sound?

EditorConfig helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs.

xuhdev commented 5 years ago

@jedmao :+1: I like that, but I would emphasize "various editors and IDEs." The sentence sounds as if it is an extra (not core) feature to accommodate multiple editors/IDEs. How about removing "potentially"?

jednano commented 5 years ago

How about replacing "potentially" with "across" various editors? I've edited the post up there with the new verbage.

xuhdev commented 5 years ago

:+1: Awesome! Let's wait a bit for others' opinions.

xuhdev commented 5 years ago

Closed in 9e89eaae6f840635c7d7ed3a30189b6f9374d13b