You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kylin.apache.org by xx...@apache.org on 2022/10/18 08:09:45 UTC
[kylin] branch doc5.0 updated: [doc] add coding convertion (#1998)
This is an automated email from the ASF dual-hosted git repository.
xxyu pushed a commit to branch doc5.0
in repository https://gitbox.apache.org/repos/asf/kylin.git
The following commit(s) were added to refs/heads/doc5.0 by this push:
new 69d1ba30dd [doc] add coding convertion (#1998)
69d1ba30dd is described below
commit 69d1ba30ddf99d48645351ea5908ecedf376250c
Author: Tengting Xu <34...@users.noreply.github.com>
AuthorDate: Tue Oct 18 16:09:36 2022 +0800
[doc] add coding convertion (#1998)
* [doc] add coding convertion
* Minor fix
* Minor fix
* Minor fix
---
website/docs/development/coding_convention.md | 87 +++++++++++++++++++++
.../coding_convention/coding_convention_1.png | Bin 0 -> 270515 bytes
.../coding_convention/coding_convention_2.png | Bin 0 -> 207742 bytes
.../coding_convention/coding_convention_3.png | Bin 0 -> 94367 bytes
.../coding_convention/coding_convention_4.png | Bin 0 -> 363452 bytes
website/sidebars.js | 4 +
6 files changed, 91 insertions(+)
diff --git a/website/docs/development/coding_convention.md b/website/docs/development/coding_convention.md
new file mode 100644
index 0000000000..68c64710d1
--- /dev/null
+++ b/website/docs/development/coding_convention.md
@@ -0,0 +1,87 @@
+---
+title: Coding and Naming Convention
+language: en
+sidebar_label: Coding and Naming Convention
+pagination_label: Coding and Naming Convention
+toc_min_heading_level: 2
+toc_max_heading_level: 6
+pagination_prev: development/roadmap
+pagination_next: development/how_to_contribute
+keywords:
+ - contribute
+ - code review
+draft: false
+last_update:
+ date: 10/14/2022
+ author: Tengting Xu
+---
+
+Coding convention is very important for teamwork. Not only it keeps code neat and tidy, it saves a lot of work too. Different coding convention (and auto formatter) will cause unnecessary code changes that requires more effort at code review and code merge.
+
+## Setup IDE code formatter
+
+For Java code, we use Eclipse default formatter setting, with one change that to allow long lines.
+
+- For Eclipse developers, no manual setting is required. Code formatter configurations `src/core-common/.settings/org.eclipse.jdt.core.prefs` is on git repo. Your IDE should be auto configured when the projects are imported.
+
+- For intellij IDEA developers, you need to install `Eclipse Code Formatter` and load the Eclipse formatter settings into your IDE manually.
+
+ you have to do a few more steps:
+
+ 1. Install `Eclipse Code Formatter` and use `org.eclipse.jdt.core.prefs` and `org.eclipse.jdt.ui.prefs` in `src/core-common/.settings` to configure `Eclipse Java Formatter config file` and `Import order`.
+
+ ![](images/coding_convention/coding_convention_1.png)
+
+ 2. Go to Preference => Code Style => Java, set `Scheme` to Default, and set both Class count to use import with `*` and Names count to use static import with `*` to 99.
+
+ ![](images/coding_convention/coding_convention_2.png)
+
+ 3. Disable intellij IDEA’s `Optimize imports on the fly`
+
+ ![](images/coding_convention/coding_convention_3.png)
+
+ 4. Format the code before committing the code.
+
+## Setup IDE license header template
+
+Each source file should include the following Apache License header
+
+```shell
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```
+
+The checkstyle plugin will check the header rule when packaging also. The license file locates under `dev-support/checkstyle-apache-header.txt`. To make it easy for developers, please add the header as Copyright Profile and set it as default for Kylin project.
+
+![](images/coding_convention/coding_convention_4.png)
+
+## Code Rules(Important)
+
+1. For JavaScript, XML, and other code, please use space for indent. And as a general rule, keep your code format consistent with existing lines. No other enforcement at the moment.
+
+2. Using `StringUtils`, just use the `StringUtils` of `org.apache.commons.lang3.StringUtils` and `io.kyligence.kap.guava20.shaded.common.base.Strings`.
+
+3. Using the `guava` in the package of `io.kyligence.kap.guava20.shaded.`.
+
+4. Don't use `log4j` directly, please use `slf4j`. Lombok uses the annotation of `@Slf4j` and Factory class `org.slf4j.LoggerFactory`.
+
+5. Add a new test or modified a test.
+
+ 1) Please using the `junit5` instead of `junit4`. Example, Using the annotation of `org.junit.jupiter.api.Test` instead of `org.junit.Test`.
+
+ 2) A test case which extends from `NLocalFileMetadataTestCase` need to change with annotation `@MetadataInfo` and remove the `extend`.
+
+ > Example: org.apache.kylin.junit.MetadataExtension, org.apache.kylin.metadata.epoch.EpochManagerTest
diff --git a/website/docs/development/images/coding_convention/coding_convention_1.png b/website/docs/development/images/coding_convention/coding_convention_1.png
new file mode 100644
index 0000000000..ddc1a6dddc
Binary files /dev/null and b/website/docs/development/images/coding_convention/coding_convention_1.png differ
diff --git a/website/docs/development/images/coding_convention/coding_convention_2.png b/website/docs/development/images/coding_convention/coding_convention_2.png
new file mode 100644
index 0000000000..ac177333fe
Binary files /dev/null and b/website/docs/development/images/coding_convention/coding_convention_2.png differ
diff --git a/website/docs/development/images/coding_convention/coding_convention_3.png b/website/docs/development/images/coding_convention/coding_convention_3.png
new file mode 100644
index 0000000000..65195556ea
Binary files /dev/null and b/website/docs/development/images/coding_convention/coding_convention_3.png differ
diff --git a/website/docs/development/images/coding_convention/coding_convention_4.png b/website/docs/development/images/coding_convention/coding_convention_4.png
new file mode 100644
index 0000000000..f71ec71bdb
Binary files /dev/null and b/website/docs/development/images/coding_convention/coding_convention_4.png differ
diff --git a/website/sidebars.js b/website/sidebars.js
index 59ec7d333d..5de3b7e967 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -942,6 +942,10 @@ const sidebars = {
type: 'doc',
id: 'development/roadmap'
},
+ {
+ type: 'doc',
+ id: 'development/coding_convention'
+ },
{
type: 'doc',
id: 'development/how_to_contribute'