From 5a4e738083a623601c9605cfafe66e6683dfd955 Mon Sep 17 00:00:00 2001
From: Peter Trifanov <peter.trifanov@mail.ru>
Date: Fri, 29 Jan 2021 17:43:13 +0300
Subject: [PATCH] Describe order of top-level structures (#722)

### What's done:
* Added rule 3.1.5 description
* Changed badges in README.md
---
 README.md                     |  4 +--
 info/guide/guide-TOC.md       |  1 +
 info/guide/guide-chapter-3.md | 47 +++++++++++++++++++++++++++++++++++
 3 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 83569aa7c0..a307c25d05 100644
--- a/README.md
+++ b/README.md
@@ -2,12 +2,12 @@
 
 ![Build and test](https://github.com/cqfn/diKTat/workflows/Build%20and%20test/badge.svg)
 ![deteKT static analysis](https://github.com/cqfn/diKTat/workflows/Run%20deteKT/badge.svg)
-![diKTat code style](https://github.com/cqfn/diKTat/workflows/Run%20diKTat/badge.svg)
+![diKTat code style](https://github.com/cqfn/diKTat/workflows/Run%20diKTat%20from%20release%20version/badge.svg?branch=master)
 [![License](https://img.shields.io/github/license/cqfn/diKtat)](https://github.com/cqfn/diKTat/blob/master/LICENSE)
 [![codecov](https://codecov.io/gh/cqfn/diKTat/branch/master/graph/badge.svg)](https://codecov.io/gh/cqfn/diKTat)
 
 [![Releases](https://img.shields.io/github/v/release/cqfn/diKTat)](https://github.com/cqfn/diKTat/releases)
-![Maven Central](https://img.shields.io/maven-central/v/org.cqfn.diktat/diktat-rules)
+[![Maven Central](https://img.shields.io/maven-central/v/org.cqfn.diktat/diktat-rules)](https://mvnrepository.com/artifact/org.cqfn.diktat)
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fcqfn%2FdiKTat.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fcqfn%2FdiKTat?ref=badge_shield)
 [![ktlint](https://img.shields.io/badge/code%20style-%E2%9D%A4-FF4081.svg)](https://ktlint.github.io/)
 [![Chat on Telegram](https://img.shields.io/badge/Chat%20on-Telegram-brightgreen.svg)](https://t.me/joinchat/AAAAAFDg-ipuZFGyBGPPeg)
diff --git a/info/guide/guide-TOC.md b/info/guide/guide-TOC.md
index 4e4a4586b7..a7932210ec 100644
--- a/info/guide/guide-TOC.md
+++ b/info/guide/guide-TOC.md
@@ -38,6 +38,7 @@ I [Preface](#c0)
     * [3.1.2 Code blocks in the source file should be separated by one blank line](#r3.1.2)
     * [3.1.3 Import statements order](#r3.1.3)  
     * [3.1.4 Order of declaration parts of class-like code structures](#r3.1.4)      
+    * [3.1.5 Order of declaration of top-level code structures](#r3.1.5)
 * [3.2 Braces](#c3.2)    
     * [3.2.1 Using braces in conditional statements and loop blocks](#r3.2.1)           
     * [3.2.2 Opening braces are placed at the end of the line in *non-empty* blocks and block structures](#r3.2.2)               
diff --git a/info/guide/guide-chapter-3.md b/info/guide/guide-chapter-3.md
index ce781fe92a..9167ff0ab3 100644
--- a/info/guide/guide-chapter-3.md
+++ b/info/guide/guide-chapter-3.md
@@ -78,6 +78,53 @@ If the classes are meant to be used externally, and are not referenced inside th
 **Exception:**
 All variants of a `(private) val` logger should be placed at the beginning of the class (`(private) val log`, `LOG`, `logger`, etc.).
 
+#### <a name="r3.1.5"></a> 3.1.5 Order of declaration of top-level code structures
+Kotlin allows several top-level declaration types: classes, objects, interfaces, properties and functions.
+When declaring more than one class or zero classes (e.g. only functions), as per rule [2.2.1](#r2.2.1), you should document the whole file in the header KDoc.
+When declaring top-level structures, keep the following order:
+1. Top-level constants and properties (following same order as properties inside a class: `const val`,`val`, `lateinit var`, `var`)
+2. Interfaces, classes and objects (grouped by their visibility modifiers)
+3. Extension functions
+4. Other functions
+
+**Note**:
+Extension functions shouldn't have receivers declared in the same file according to [rule 6.2.3](#r6.2.3)
+
+Valid example:
+```kotlin
+package org.cqfn.diktat.example
+
+const val CONSTANT = 42
+
+val topLevelProperty = "String constant"
+
+interface IExample
+
+class Example : IExample
+
+private class Internal
+
+fun Other.asExample(): Example { /* ... */ }
+
+private fun Other.asInternal(): Internal { /* ... */ }
+
+fun doStuff() { /* ... */ }
+```
+
+**Note**:
+kotlin scripts (.kts) allow arbitrary code to be placed on the top level. When writing kotlin scripts, you should first declare all properties, classes
+and functions. Only then you should execute functions on top level. It is still recommended wrapping logic inside functions and avoid using top-level statements
+for function calls or wrapping blocks of code in top-level scope functions like `run`.
+
+Example:
+```kotlin
+/* class declarations */
+/* function declarations */
+run {
+    // call functions here
+}
+```
+
 <!-- =============================================================================== -->
 ### <a name="c3.2"></a> 3.2 Braces
 This section describes the general rules of using braces in your code.