Get best of the week

Bersihkan Kode SIL

SIL adalah bahasa pemrograman untuk mengotomatisasi pekerjaan di Atlassian Jira dan Confluence. Anda dapat membaca lebih lanjut tentang SIL di sini .

Saya sering bekerja dengan skrip yang ditulis dalam SIL, dan ingin membagikan pendapat saya tentang cara membuat kode SIL "bersih".

Pada artikel ini, saya pertama kali akan merumuskan aturan yang memandu saya saat menulis kode SIL, dan kemudian memberikan contoh kode dan melakukan refactoring menggunakan aturan ini.

aturan


  1. Struktur nama dimulai dengan huruf kapital.
  2. Tambahkan elemen array menggunakan metode AddElement .
  3. Gunakan rutin yang ditentukan pengguna untuk memecah kode Anda menjadi blok logis dan menyingkirkan komentar dalam kode.
  4. Bawa kode yang dapat digunakan kembali ke perpustakaan ( inklusi ).
  5. Deklarasikan struktur sebelum sisa deklarasi variabel.
  6. Berikan nama yang bermakna ke struktur dan variabel, dalam hal ini Anda tidak perlu menambahkan komentar tambahan ke struktur dan variabel.
  7. Beri nama variabel dan fungsi sesuai dengan panduan gaya Google Java .

Sekarang mari kita lihat contoh kode SIL.

string USER = currentUser();
// Response
struct returnData {
    string status;
}
// Project
struct space {
    string key;
}
// Inner part with content
struct storage {
    string value;
    string representation;
}
// Part for storage
struct body {
    storage storage;
}
// Main entity for sending to Confluence
struct reqData {
    string type;
    string title;
    space space;
    body body;
}
reqData data;
data.type = "page";
data.title = "Page for issue " + key + "  " + summary + ".";
data.space.key = project;
data.body.storage.value = "<p> Author:"+userFullName(USER) + " description: "  + description + "</p>";
data.body.storage.representation = "storage";
// Create request
HttpRequest request;
HttpHeader header = httpCreateHeader("Content-Type", "application/json");
HttpHeader authHeader = httpBasicAuthHeader("admin", "admin");
request.headers += header;
request.headers += authHeader;
logPrint("WARN", request);
//POST
string JSONData = toJson(data);
logPrint("WARN", JSONData);
returnData result = httpPost("http://192.168.54.203:8090/rest/api/content/", request, JSONData);
string errMsg = httpGetErrorMessage();
logPrint("ERROR", "Last error message: " + errMsg);
logPrint("WARN", result);
string COMMENT = "Page created in Confluence " + updated + " by " + userFullName(USER) + " Status : " +result.status + "."; 
addComment(key, USER, COMMENT);
//Return Status
return result.status;

Melihat kode itu cukup sulit untuk dengan cepat menentukan apa yang dilakukan kode. Komentar dalam kode juga tidak banyak membantu. Ayo coba ubah kode sesuai aturan di atas.

Pertama lihat strukturnya. Ini salah satu contohnya:

struct body {
    storage storage;
}

Kita melihat bahwa "penyimpanan penyimpanan" terlihat tidak dapat dipahami. Akan lebih jelas jika kodenya seperti ini:

struct body {
    Storage storage;
}

Sekarang kita melihat bahwa kita mendefinisikan bidang dalam struktur di bawah nama penyimpanan tipe Penyimpanan. Agar kita dapat menulis kode seperti itu, kita perlu membuat huruf pertama dari setiap struktur dengan huruf besar:

// Response
struct ReturnData {
    string status;
}
// Project
struct Space {
    string key;
}
// Inner part with content
struct Storage {
    string value;
    string representation;
}
// Part for storage
struct Body {
    Storage storage;
}
// Main entity for sending to Confluence
struct ReqData {
    string type;
    string title;
    Space space;
    Body body;
}

Sekarang mari kita rename struktur sehingga nama struktur membuatnya jelas mengapa itu diperlukan, dan kita tidak perlu menambahkan komentar:

struct Space {
    string key;
}
struct Storage {
    string value;
    string representation;
}
struct Body {
    Storage storage;
}
struct CreateConfluencePageRequest {
    string type;
    string title;
    Space space;
    Body body;
}
struct CreateConfluencePageResponse {
    string status;
}

Menurut pendapat saya, nama-nama tersebut tidak memerlukan komentar tambahan untuk struktur. Kami juga akan mendeklarasikan struktur di awal kode.

Kami menggunakan Aturan 1, 5, 6.

Sekarang mari kita lihat kode setelah deklarasi struktur:

string USER = currentUser();
CreateConfluencePageRequest data;
data.type = "page";
data.title = "Page for issue " + key + "  " + summary + ".";
data.space.key = project;
data.body.storage.value = "<p> Author:"+userFullName(USER) + " description: "  + description + "</p>";
data.body.storage.representation = "storage";
// Create request
HttpRequest request;
HttpHeader header = httpCreateHeader("Content-Type", "application/json");
HttpHeader authHeader = httpBasicAuthHeader("admin", "admin");
request.headers += header;
request.headers += authHeader;
logPrint("WARN", request);
//POST
string JSONData = toJson(data);
logPrint("WARN", JSONData);
CreateConfluencePageResponse result = httpPost("http://192.168.54.203:8090/rest/api/content/", request, JSONData);
string errMsg = httpGetErrorMessage();
logPrint("ERROR", "Last error message: " + errMsg);
logPrint("WARN", result);
string COMMENT = "Page created in Confluence " + updated + " by " + userFullName(USER) + " Status : " +result.status + "."; 
addComment(key, USER, COMMENT);
//Return Status
return result.status;

Melihat kode, kita tidak dapat dengan cepat memahami apa yang terjadi dalam kode. Pertama mari kita coba memecah kode menjadi blok logis:

getNewConfluencePageContent();
createHttpRequest();
createConfluencePage();
addCommentToJiraIssue();

Artinya, pertama kita mendapatkan konten halaman baru di Confluence, lalu buat permintaan http, buat halaman di Confluence dan tulis komentar di permintaan Jira agar halaman di Confluence dibuat. Sekarang mari kita terapkan fungsi-fungsi ini:

function getNewConfluencePageContent() {
    CreateConfluencePageRequest data;
    data.type = "page";
    data.title = "Page for issue " + key + "  " + summary + ".";
    data.space.key = project;
    data.body.storage.value = "<p> Author:"+userFullName(currentUser()) + " description: "  + description + "</p>";
    data.body.storage.representation = "storage";
    return toJson(data);
}

function createHttpRequest() {
    HttpRequest request;
    HttpHeader header = httpCreateHeader("Content-Type", "application/json");
    HttpHeader authHeader = httpBasicAuthHeader("admin", "admin");
    request.headers = addElement(request.headers, header);
    request.headers += addElement(request.headers, authHeader);
    logPrint("WARN", request);
    return request;
}

function createConfluencePage(string pageJson) {
    HttpRequest request = createHttpRequest();
    CreateConfluencePageResponse result = httpPost("http://192.168.54.203:8090/rest/api/content/", request, pageJson);
    logPrint("ERROR", "Last error message: " + httpGetErrorMessage());
    logPrint("WARN", result);
    return result;
}

function addCommentToJiraIssue(string resultStatus) {
    string COMMENT = "Page created in Confluence " + updated + " by " + userFullName(currentUser()) + " Status : " +resultStatus + "."; 
    addComment(key, currentUser(), COMMENT);
}

string pageJson = getNewConfluencePageContent();
CreateConfluencePageResponse result = createConfluencePage(pageJson);
addCommentToJiraIssue(result.status);
return result.status;

Kami menghapus blok logis dalam fungsi (Aturan 2). Sekarang kita cukup menulis kode seperti ini:

string pageJson = getNewConfluencePageContent();
CreateConfluencePageResponse result = createConfluencePage(pageJson);
addCommentToJiraIssue(result.status);
return result.status;

Kode kami berisi empat blok logis. Pertama kita mendapatkan json dari halaman baru, kemudian membuat halaman di Confluence, menambahkan komentar ke permintaan dan mengembalikan status pembuatan halaman ke Confluence. Keempat baris ini memberi kita pandangan tingkat atas tentang apa yang dilakukan skrip. Jika kita ingin memahami konten halaman dalam Confluence, maka kita selalu dapat membuka getNewConfluencePageContent dan melihat konten dari fungsi ini. Fungsi ini hanya berisi kode untuk membuat konten halaman dan tidak lebih, sehingga, sambil mempelajari kode fungsi, kami tidak akan terganggu oleh fungsionalitas lain.

Kita dapat berasumsi bahwa kita perlu membuat halaman dalam Confluence tidak hanya dari satu skrip. Oleh karena itu, mari kita buat file confluence_helper.incl dan matikan semua fungsi yang diperlukan untuk membuat halaman di Confluence ke file ini:

struct Space {
    string key;
}
struct Storage {
    string value;
    string representation;
}
struct Body {
    Storage storage;
}
struct CreateConfluencePageRequest {
    string type;
    string title;
    Space space;
    Body body;
}
struct CreateConfluencePageResponse {
    string status;
}

function createHttpRequest() {
    HttpRequest request;
    HttpHeader header = httpCreateHeader("Content-Type", "application/json");
    HttpHeader authHeader = httpBasicAuthHeader("admin", "admin");
    request.headers = addElement(request.headers, header);
    request.headers += addElement(request.headers, authHeader);
    logPrint("INFO", request);
    return request;
}

function createConfluencePage(string confluenceUrl, string pageJson) {
    HttpRequest request = createHttpRequest();
    CreateConfluencePageResponse result = httpPost(confluenceUrl, request, pageJson);
    logPrint("ERROR", "Last error message: " + httpGetErrorMessage());
    logPrint("INFO", result);
    return result;
}

Saya membuat fungsi createConfluencePage lebih umum dengan menambahkan parameter confluenceUrl lain ke dalamnya. Jadi, kami mengikuti Aturan 4.

Sekarang skrip utama kami akan terlihat seperti ini:

include "confluence_helper.incl";

function getNewConfluencePageContent() {
    CreateConfluencePageRequest data;
    data.type = "page";
    data.title = "Page for issue " + key + "  " + summary + ".";
    data.space.key = project;
    data.body.storage.value = "<p> Author:"+userFullName(currentUser()) + " description: "  + description + "</p>";
    data.body.storage.representation = "storage";
    return toJson(data);
}

function addCommentToJiraIssue(string resultStatus) {
    string comment = "Page created in Confluence " + updated + " by " + userFullName(currentUser()) + " Status : " +resultStatus + "."; 
    addComment(key, currentUser(), comment);
}


const string CONFLUENCE_URL = "http://192.168.54.203:8090/rest/api/content/";

string pageJson = getNewConfluencePageContent();
CreateConfluencePageResponse result = createConfluencePage(CONFLUENCE_URL, pageJson);
addCommentToJiraIssue(result.status);
return result.status;

Pada baris pertama, saya menyertakan file confluence_helper.incl untuk menggunakan fungsi pembuatan halaman dalam Confluence darinya.

Saya menyimpan alamat Confluence dalam variabel konstan dan mengubah nama variabel sesuai dengan gaya notasi Google Java (Aturan 7).

Sepertinya saya bahwa ini dapat dihentikan dengan refactoring. Sebagai hasil dari refactoring, kami mendapatkan fungsi pembuatan halaman yang dapat digunakan kembali dalam Confluence, dan kode kami menjadi lebih mudah dibaca dan didukung.

More articles:


All Articles