تنظيف كود SIL

SIL هي لغة برمجة لأتمتة العمل في Atlassian Jira and Confluence. يمكنك قراءة المزيد عن SIL هنا .

غالبًا ما أعمل مع نصوص مكتوبة بلغة SIL ، وأود أن أشارككم أفكاري حول كيفية جعل رمز SIL "نظيفًا".

في هذه المقالة ، سأقوم أولاً بصياغة القواعد التي أتبعها عند كتابة كود SIL ، ثم أعطى مثالاً على الرمز وأقوم بإعادة البناء باستخدام هذه القواعد.

قواعد


  1. تبدأ هياكل الأسماء بحرف كبير.
  2. أضف عناصر الصفيف باستخدام طريقة AddElement .
  3. استخدم إجراءات يحددها المستخدم لتقسيم التعليمات البرمجية إلى كتل منطقية والتخلص من التعليقات في التعليمات البرمجية.
  4. جلب كود قابلة لإعادة الاستخدام للمكتبات ( الادراج ).
  5. قم بتعريف الهياكل قبل باقي التصريح عن المتغير.
  6. قم بإعطاء أسماء ذات معنى للهياكل والمتغيرات ، في هذه الحالة لن تضطر إلى إضافة تعليقات إضافية إلى الهياكل والمتغيرات.
  7. قم بتسمية المتغيرات والوظائف وفقًا لدليل أنماط Google Java .

الآن دعونا نلقي نظرة على مثال لرمز 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;

من الصعب جدًا النظر إلى الشفرة لتحديد ما تفعله الشفرة. التعليقات في الكود لا تساعد كثيرا لنحاول تغيير الرمز وفقًا للقواعد أعلاه.

نظرة أولى على الهيكل. هنا مثال واحد:

struct body {
    storage storage;
}

نرى أن "تخزين التخزين" يبدو غير مفهوم. سيكون من الواضح إذا كان الرمز على النحو التالي:

struct body {
    Storage storage;
}

نرى الآن أننا نحدد حقلاً في البنية تحت اسم تخزين نوع التخزين. لكي نكتب مثل هذا الرمز ، نحتاج إلى جعل الحرف الأول من كل هيكل مكتوبًا بالأحرف الكبيرة:

// 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;
}

الآن دعنا نعيد تسمية الهيكل بحيث يوضح اسم الهيكل سبب الحاجة إليه ، ولن نضطر إلى إضافة تعليقات:

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;
}

في رأيي ، لا تتطلب هذه الأسماء تعليقات إضافية للهياكل. سنعلن أيضًا الهياكل في بداية الكود.

استخدمنا القواعد 1 ، 5 ، 6.

الآن دعونا نلقي نظرة على الكود بعد إعلان البنى:

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;

بالنظر إلى الرمز ، لا يمكننا أن نفهم بسرعة ما يحدث في الرمز. دعونا أولاً نحاول كسر الشفرة إلى كتل منطقية:

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

أي أننا نحصل أولاً على محتويات الصفحة الجديدة في Confluence ، ثم نقوم بإنشاء طلب http وإنشاء صفحة في Confluence وكتابة تعليق في طلب Jira بإنشاء الصفحة في Confluence. الآن دعنا ننفذ هذه الوظائف:

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;

أزلنا الكتل المنطقية في الوظيفة (القاعدة 2). الآن يمكننا ببساطة كتابة الرمز مثل هذا:

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

كودنا يحتوي على أربع كتل منطقية. أولاً نحصل على json للصفحة الجديدة ، ثم ننشئ الصفحة في Confluence ، ونضيف تعليقًا على الطلب ونعيد حالة إنشاء الصفحة إلى Confluence. تقدم لنا هذه الأسطر الأربعة عرضًا عالي المستوى لما يفعله البرنامج النصي. إذا أردنا فهم محتويات الصفحة في Confluence ، فيمكننا دائمًا الانتقال إلى getNewConfluencePageContent والاطلاع على محتويات هذه الوظيفة. تحتوي هذه الوظيفة على رمز فقط لإنشاء محتوى الصفحة وليس أكثر من ذلك ، وبالتالي ، أثناء دراسة رمز الوظيفة ، لن تشتت انتباهنا وظيفة أخرى.

يمكننا أن نفترض أننا سنحتاج إلى إنشاء صفحات في Confluence ليس فقط من نص برمجي واحد. لذلك ، دعنا ننشئ ملف confluence_helper.incl ونطرح جميع الوظائف اللازمة لإنشاء صفحة في Confluence لهذا الملف:

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;
}

لقد جعلت وظيفة createConfluencePage أكثر عمومية من خلال إضافة معلمة confluenceUrl أخرى إليها. وهكذا ، اتبعنا القاعدة 4.

والآن سيبدو نصنا الرئيسي كما يلي:

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;

في السطر الأول ، قمت بتضمين ملف confluence_helper.incl لاستخدام وظيفة إنشاء الصفحة في Confluence منه.

لقد حفظت عنوان Confluence في متغير ثابت وقمت بتغيير أسماء المتغيرات وفقًا لنمط تدوين Java Java (القاعدة 7).

يبدو لي أنه يمكن إيقاف ذلك عن طريق إعادة الهيكلة. نتيجة لإعادة الهيكلة ، حصلنا على وظيفة إنشاء صفحة قابلة لإعادة الاستخدام في Confluence ، وأصبح رمزنا أكثر قابلية للقراءة ودعمه.

All Articles