anchor.diff:  [[sec:improving_task_discoverability]]
   === Improving task discoverability
   
  -Even new users to a build should to be able to find crucial information quickly and effortlessly. In Gradle you can declare a api:org.gradle.api.Task#setGroup(java.lang.String)[group] and a api:org.gradle.api.Task#setDescription(java.lang.String)[description] for any task of the build. The <<sec:listing_tasks,tasks report>> uses the assigned values to organize and render the task for easy discoverability. Assigning a group and description is most helpful for any task that you expect build users to invoke.
  -
  -The example task `generateDocs` generates documentation for a project in the form of HTML pages. The task should be organized underneath the bucket `Documentation`. The description should express its intent.
  +Even new users to a build should to be able to find crucial information quickly and effortlessly.
  +In Gradle you can declare a api:org.gradle.api.Task#setGroup(java.lang.String)[group] and a api:org.gradle.api.Task#setDescription(java.lang.String)[description] for any task of the build.
  +The <<sec:listing_tasks,tasks report>> uses the assigned values to organize and render the task for easy discoverability.
  +Assigning a group and description is most helpful for any task that you expect build users to invoke.
  +
  +The example task `generateDocs` generates documentation for a project in the form of HTML pages.
  +The task should be organized underneath the bucket `Documentation`.
  +The description should express its intent.
   
   ++++
   <sample id="taskGroupDescription" dir="userguide/bestPractices/taskGroupDescription" title="A task declaring the group and description">
  
positive.code: 
  ==== Alternatives for oft-used internal APIs
  
  To provide a nested DSL for your custom task, don't use `org.gradle.internal.reflect.Instantiator`; use api:org.gradle.api.model.ObjectFactory[] instead. It may also be helpful to read <<lazy_configuration>>.
  
  Don't use `org.gradle.api.internal.ConventionMapping`. Use api:org.gradle.api.provider.Provider[] and/or api:org.gradle.api.provider.Property[]. You can find an example for capturing user input to configure runtime behavior in the link:https://guides.gradle.org/implementing-gradle-plugins/#capturing_user_input_to_configure_plugin_runtime_behavior[implementing plugins guide].
  
  Instead of `org.gradle.internal.os.OperatingSystem`, use another method to detect operating system, such as link:https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/SystemUtils.html[Apache commons-lang SystemUtils] or `System.getProperty("os.name")`.
  
  
negative.code: [[sec:avoid_imperative_logic_in_scripts]]
  === Avoiding imperative logic in scripts
  
  The Gradle runtime does not enforce a specific style for build logic.
  For that very reason, it's easy to end up with a build script that mixes declarative DSL elements with imperative, procedural code.
  Let's talk about some concrete examples.
  
  * _Declarative code:_ Built-in, language-agnostic DSL elements (e.g. api:org.gradle.api.Project#dependencies(groovy.lang.Closure)[] or api:org.gradle.api.Project#repositories(groovy.lang.Closure)[]) or DSLs exposed by plugins
  * _Imperative code:_ Conditional logic or very complex task action implementations
  
  The end goal of every build script should be to only contain declarative language elements which makes the code easier to understand and maintain.
  Imperative logic should live in binary plugins and which in turn is applied to the build script.
  As a side product, you automatically enable your team to link:https://guides.gradle.org/designing-gradle-plugins/#reusable_logic_should_be_written_as_binary_plugin[reuse the plugin logic in other projects] if you publish the artifact to a binary repository.
  
  The following sample build shows a negative example of using conditional logic directly in the build script.
  While this code snippet is small, it is easy to imagine a full-blown build script using numerous procedural statements and the impact it would have on readability and maintainability.
  By moving the code into a class link:https://guides.gradle.org/testing-gradle-plugins/[testability] also becomes a valid option.
  
  ++++
  <sample id="conditionalLogicDont" dir="userguide/bestPractices/conditionalLogic/dont" title="A build script using conditional logic to create a task">
  